6REST APIs for SAM
REST APIs for SAM
Siebel Approval Manager (SAM) has a plug-n-play architecture using REST APIs. REST APIs are used to feed data from external systems into SAM as well as write data back to those external systems. These external systems can be either Issue Tracking systems like Bugzilla or SCM (Software Configuration Management) systems like GitHub or Siebel Workspace.
GET REST API is used for reading (specified as the Read/Update property in SAM System administration), providing the query data element part of the URI. POST REST API is used for writing (specified as the Write/Deliver property) of any data change that need to be pushed to external systems.
This chapter describes sample REST APIs. This chapter includes the following topics:
REST API GET URL Sample Format for Issue Tracking Systems
The sample format is as follows:
http://<server ip>/services/bugzilla/<issue ID>
REST API GET Method's JSON Format for Issue Tracking Systems
The GET method exposed by an external system's REST API needs to follow a certain JSON format, which is readable by SAM. The JSON must have a 'key identifier' property representing an issue's unique identifier (such as Bugzilla's bug number) and a 'key status' property which represents the lifecycle state of the issue (such as Bugzilla's status field).
GET JSON needs to be an array with single or multiple elements.
JSON sample:
[ { "issueId": "17788411", "status": "Approved, waiting for codeline to open", "priority": "1", "customer": "INTERNAL", "severity": "2", "publish": "N", "statusId": "39" }, { " issueId ": "22809179", "status": "Closed, Not a Bug", "priority": "5", "customer": "INTERNAL", "severity": "2", "publish": "N", "statusId": "92" }, { " issueId ": "22809190", "status": "Closed, Not a Bug", "priority": "5", "customer": "INTERNAL", "severity": "2", "publish": "N", "statusId": "92" } ]
REST API POST URL Sample Format for Issue Tracking Systems
The sample format is as follows:
http://<server ip>/services/issue/
REST API POST Method's JSON Format for Issue Tracking Systems
The JSON format expected by POST should also follow a certain format. The JSON must have a 'key identifier' representing the issue's key that GET. POST JSON need to be a simple structure without any array.
JSON sample:
{ " issueId ": "22809190", "publish": "N", "statusId": "92" }
In the above sample "issueId", which is the 'key identifier', will help the POST end point identify which Issue/Bug is going to get updated. The other two fields, "publish" and "statusId", are the two fields that are going to get updated with values supplied in the JSON.
Importing System Fields
A static GET end point has to be used to import field metadata that the 'Issue Tracking System' supports. This end point will bring two properties namely, 'fieldName' and 'fieldId'. 'fieldName' represents the name of the field and 'fieldId' represents a unique identifier which is also used for order of the fields while being imported in SAM. All the available fields in GET and POST mentioned earlier need to be represented in the JSON output.
URL: http://<server ip>/services/bugzilla/fields/
JSON sample:
[ { "fieldName": "issueId", "fieldId": "0" }, { "fieldName": "status", "fieldId": "1" }, { "fieldName": " priority ", "fieldId": "2" }, { "fieldName": " customer ", "fieldId": "3" }, { "fieldName": " severity", "fieldId": "4" }, { "fieldName": " publish", "fieldId": "5" }, { "fieldName": " statusId ", "fieldId": "6" } ]
REST API GET URL Sample Formats for SCM Systems
Configured URL in SAM: http://<server ip>/services/github/<source>
URL runtime formation sample:
http://<server ip>/services/github/dev_fix_for_inline_edit
source = dev_fix_for_inline_edit
For example if the URL needs 'repository' and 'version' (in addition to the built-in branch name placeholder for 'source') then providing the element in the below format is required.
Sample URL:
Configured URL in SAM: http://<server ip>/github/repos/<repository>/<version>/commits/<source>
URL runtime formation sample:
http://<server ip>/github/repos/siebelsam/sam-demo/commits/dev_fix_for_inline_edit
repository = siebelsam
version = sam-demo
source = dev_fix_for_inline_edit
REST API GET Method's JSON Format for SCM Systems
GET method for SCM systems is a strictly formatted set of properties. The information required for GET URI is passed via URI format.
{ "valid": "N", "message": "Workspace status is invalid." }
The property 'valid' can have either 'Y', which stands for a valid branch, or 'N', which stands for an invalid or an already closed branch. 'Message' can contain a string with the reason for declaring the branch invalid or any message for valid branch (such as list of affected files, etc.).
GET REST API Exposed by SAM for Approval Requests
SAM provides a built-in GET REST API to access Approval Request information.
Sample:
http://<server ip>/sam/approvals/88@93
'88@93' in the above URL is Approval Id.
Output:
{ "message": "", "data": [ { "approvalId": "88@93", "seedIssue": "Y", "profileId": "88@30990610", "defaultActionId": null, "closeStatus": null, "fieldsAndData": [ { "fieldmapId": "88@30990653", "genericFieldId": null, "genericFieldLabel": null, "genericFieldName": "APPROVAL_ID", "extFieldName": "APPROVAL_ID", "overrideLabel": "Approval Id", "fieldValue": "88@93", "valid": null, "drillDownURL": null, "defaultView": "N", "header": "N", "validationText": null, "keyField": "N", "systemId": "0CX@32325372", "systemname": "System", "displayOrder": 1 }, { "fieldmapId": "88@30990654", "genericFieldId": null, "genericFieldLabel": null, "genericFieldName": "APPROVAL_STATUS", "extFieldName": "APPROVAL_STATUS", "overrideLabel": "Approval Status", "fieldValue": "Draft", "valid": null, "drillDownURL": null, "defaultView": "N", "header": "N", "validationText": null, "keyField": "N", "systemId": "0CX@32325372", "systemname": "System", "displayOrder": 2 }, ], "buttons": null, "scmSystems": null, "approvalAuditTrail": [ { "atId": "88@94", "approvalId": "88@93", "approvalStatusId": "88@30993086", "approvalStatus": "Draft", "comments": null, "overrideManagerId": "null", "overrideManager": null, "updatedById": "88@30993489", "updatedByEmail": "thirupathi.rajendran@oracle.com", "updatedBy": "Thirupathi Rajendran", "updated": 1501064367000, "version": null } ] } ] }
POST REST API Exposed by SAM for Workflow Actions
SAM provides a built-in POST REST API to do Approval Request actions.
Sample:
http://<server id>/sam/api/approvals/88@93?actionId=88@85
'88@93' in the above URL represent 'Approval Id' and '88@85' represents the 'Action Id', which will be performed. The 'Action Id' can be found in the Action Id field of the Workflow Actions popup on the Profile administration screen within SAM.
Output:
The 'message' contains a string explaining the outcome, either that the action is completed or was not able to be performed because of some reason. The 'data' property will always be empty. The positive output will return 200 as its status code.
{ "message": "Approval Request status changed to Draft", "data": null }
The negative output will return 409 or 500 as status code.
{ "message": "Approval Request status cannot be changed to null", "data": null }
For more examples, see https://github.com/OracleSiebel/ConfiguringSiebel/tree/master/ExampleCode/SAM.