This article provides examples of some common operations using the SystemWeaver Rest API.
Prerequisites
- It is helpful to have a basic understanding of the SystemWeaver meta model building blocks
PATCH
| Note: PropertyCommands are case sensitive!! |
| Note: Last update has to be included in each request to make sure nobody else has updated the data since you read it. |
Use the verb PATCH and e.g., which item that should be updated, and add the last updated information:
/items/x0400000000019FA9/lastupdate/2020-02-18T10:40:21.883
In the body, send information about:
- Which operation that will be applied: "Add", "Update", "Delete"
- Which property that should be updated, e.g., "attributes"
- Which identifier type that will be used: "sid" or "handle"
- Which identifier that corresponds to the property that should be updated. For a sid, it can be, e.g., "MTA"
- The value that the property should get: "test value"
To find out if there are errors, check the validationMessage at the end of the response.
PATCH a Single Value
Example: Update Foreign Id
URL (verb PATCH):
/items/x0400000000019FA9/lastupdate/2020-02-18T10:40:21.883
To patch a single value, like the item's foreign id, use the following.
Body:
{
"propertyCommands": [
{
"operation": "Update",
"propertyName": "foreignId",
"value": "test value"
}
]
}The result will be:
{
"response": {
"handle": "x040000000001A06F",
"name": "i3",
"foreignId": "test value"
}
}PATCH Item Lists Like Attributes and Parts
When adding the attribute, you should send the following.
Example: Add attribute
Url (verb PATCH):
/items/x0400000000019FA9/lastupdate/2020-02-18T10:40:21.883
Body:
{
"propertyCommands": [
{
"operation": "Add",
"propertyName": "attributes",
"identifierType": "sid",
"identifier": "MTA",
"value": "test value"
}
]
}If patching an item, and item is returned and you can verify that the properties that you wanted to patch really are updated. In this case, we added an attribute:
{
"response": {
"handle": "x0400000000019FA9",
"name": "i3",
"type": {
"handle": "x0200000000019F9A",
"name": "Application SW Component",
"sid": "ARAP"
},
"attributes": [
{
"attributeType": {
"handle": "x1600000000000554",
"sid": "MTA",
"name": "Meta test attribute",
"dataType": "String",
"dataDimension": "Single",
"value": "test value"
}
}
],
"validationMessage": {
"validationStatus": "OK",
"validationMessages": []
}
}
}Check that there are no errors by reading the validationMessage in the response.
Example: Update Attribute
Do exactly as "Add attribute" but use the operation "Update" instead.
Body:
{
"propertyCommands": [
{
"operation": "Update",
"propertyName": "attributes",
"identifierType": "sid",
"identifier": "MTA",
"value": "test value"
}
]
}Example: Update Attribute by Handle Instead of SID
Change identifierType to "handle" and send the handle of the attribute that is going to be updated.
Body:
{
"propertyCommands": [
{
"operation": "Update",
"propertyName": "attributes",
"identifierType": "handle",
"identifier": "x1600000000000554",
"value": "test value"
}
]
}Example: Delete Attribute
Body:
{
"propertyCommands": [
{
"operation": "Delete",
"propertyName": "attributes",
"identifierType": "handle",
"identifier": "x1600000000000554",
"value": "test value"
}
]
} Example: Add Part, defObj
Url (verb PATCH):
/items/x0400000000019FA9/lastupdate/2020-02-18T10:40:21.883
To add a part is very similar to add an attribute, but the defObject has to be defined in a JSON format:
Body:
{
"propertyCommands": [
{
"operation": "Add",
"propertyName": "parts",
"identifierType": "sid",
"identifier": "ARPP",
"value": "{defObject:{handle:\"x040000000001A082\"}}"
}
]
} If you have a refObject, define it like this:
"value": "{defObject:{handle:\"x040000000001A098\"}, refObject:{handle:\"x040000000001A096\"}}"
The delete part follows the pattern of the attributes.
| Note: Update part is not yet implemented. |
PATCH Issue Relations
Example: Add a Relation
Url (verb PATCH):
/issues/x2D00000000355CB9/lastupdate/2020-10-19T11:24:27.425
Body:
{
"propertyCommands": [
{
"operation": "Add",
"propertyName": "referenceObjects",
"value": "{\"issueRefType\":{\"handle\":\"x0B00000000355CE2\"},\"referenceObject\":{\"handle\":\"x0400000000355D3C\"}}"
}
]
}The value defines the new Relation where issueRefType is the Type for the Relation, in this case defined byt its Handle. The referenceObject defines the object that the new Relation shall point to, defined by its handle. Depending on the IssueRefType, this can be either an Item or an Issue.
Example: Delete a Relation
Url (verb PATCH):
/issues/x2D00000000355CB9/lastupdate/2020-10-19T11:24:27.425
Body:
{
"propertyCommands": [
{
"operation": "Delete",
"propertyName": "referenceObjects",
"value": "{\"handle\":\"x3000000000355D3E\"}"
}
]
}The value defines the Relation to be deleted defined by its handle.
Example: Update a Relation
| Note: Only works for Relations with multiplicity single. For Relations with multiplicity List you have to Delete the old Relation and Add a new one. |
Url (verb PATCH):
/issues/x2D00000000355CB9/lastupdate/2020-10-19T11:24:27.425
Body:
{
"propertyCommands": [
{
"operation": "Update",
"propertyName": "referenceObjects",
"value": "{\"handle\":\"x3000000000355D46\",\"referenceObject\":{\"handle\":\"x0400000000355D41\"}}"
}
]
}The value defines the Relation to be updated defined by its handle. The referenceObject defines the object that the Relation shall point to, defined by its handle. Depending on the IssueRefType, this can be either an Item or an Issue.
Validation messages
If a validation error happens during PATCH, status code is <> from 200 (Success) and the errors are returned as validation messages.
{
"validationMessage": {
"validationStatus": "Failed",
"validationMessages": [
{
"status": "Failed",
"message": "A newer version of this item exists.",
"handle": null,
"objectType": "LibraryItem",
"property": "LastUpdate"
}
]
}
}POST
Create New Item
To create a new item use the following:
Url (verb POST)
/items/
Body:
{
"name": "Mrs Test",
"typeIdentifier": "x020000000001A0A1",
"homeLibraryHandle": "x1300000000000017"
} To create a new item and update more properties than the above, you can use one or many property commands.
Body:
{
"name": "Mrs Test",
"typeIdentifier": "x020000000001A0A1",
"homeLibraryHandle": "x1300000000000017",
"propertyCommands": [
{
"operation": "update",
"propertyName": "foreignId",
"value": "abc 123"
}
]
}Create New Version
To create a new version of the item use the following:
Url (verb POST)
/items/x040000000001A0C4/newversion
Command properties can be applied also to "newversion".