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 previous 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 following 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.).
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 previous 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.
Perform the following to update the status on workspace delivery.
Find the action Id required for status update. To find,
Login to SAM as administrator.
Go to Main menu, Administrator.
Click to drill down to the profile.
Find the Action under Workflow section.
Click to bring up the Action pop-up screen to find the Action Id in the Approval Profile Actions screen.
Flip SAM status post-delivery using the Action Id found in step 1. Do the following,
Make the content type as application/json.
Provide authentication details of the user who is part of the action owner role.
Make a POST call to http://<SAM server>/sam/api/approvals/88@30994552?actionId=88@30991159. Output appears as below in Postman.
{ "message": "Approval Request status changed to Ready for Build", "data": null }
GET REST API Exposed by SAM to Retrieve Status Types
SAM provides a built-in GET REST API to access a list of all of the configured approval statuses.
To get list of statuses, make a GET call to http://<SAM server>/sam/status using the Postman application.
{
"data": [
{
"statusId": "88@30993086",
"statusName": "Draft",
},
{
"statusId": "88@30993089",
"statusName": "Pending Manager Approval",
},
{
"statusId": "0CX@32325368",
"statusName": "New",
}
]
}
GET REST API Exposed by SAM to Retrieve User Types
SAM provides a built-in GET REST API to access a list of all of the configured users.
To get list of user types, make a GET call to http://<SAM server>/sam/users.
{
"uId": "0CX@32325363",
"userId": null,
"userName": "Admin",
},
GET REST API Exposed by SAM to Retrieve List of Profiles
SAM provides a built-in GET REST API to access a list of all of the configured approval request profiles.
To get the list of profiles, make a GET call to http://<SAM server>/sam/profiles.
The JSON output will contain information such as
{
"profileName": "2.17.x",
"profileId": "88@30990605",
…
REST API Exposed by SAM to Retrieve Approval Requests
APIs are built for searching SAM requests. The SAM requests could be the following:
Query based on a single approval request by its approval Id.
Query based on multi-query request tokens like Profile Id, Status and so on.
Query Based on a Single Approval Request
The 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 previous 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
}
]
}
]
}
Query Based on Multi-Query Request Tokens
APIs are built for searching SAM requests based on multiple query tokens like Profile Id, Status and so on. You can use Google Chrome app, Postman or a similar HTTP client to test the REST APIs mentioned below.
To make a query request
To make a query request
Find the query token data that you need.
The following could be some of the query tokens and the way to find them. The details are in the following topics.
STATUS_ID: Make a GET call on the Status API to find the statusId value that you want for a particular status.
MANAGER_ID and OWNER_ID: Make a GET call on the Users API to get all the users with their Ids in the property named ‘uId’.
PROFILE_ID: Make a GET call on the Profile API to get the profileId of the profile to query on.
ISSUE_ID: This is the actual Issue Id generated by your Issue Tracker.
-
Query using the data. Make a POST call to http://<SAM server>/sam/api/approvals.
Make the content type as application/json.
Provide authentication details of the user who has administrative privileges.
Provide the JSON content, like the sample here according to your requirement, in the request body.
Sample of a single query criteria. This will return all of the approval requests created using the provided Profile.
{ "PROFILE_ID":"88@30990605" }Sample of a dual query criteria. This will return all of the approval requests created using the provided Profile and are in the provided Status.
{ "PROFILE_ID":"88@30990610", "APPROVAL_STATUS_ID":"88@30993086" }The output format is identical to the one listed for the single approval request.