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.

NOTE:  The GET/POST end-points should be open without any authentication.

REST API GET URI sample format for Issue Tracking systems

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"

}

]

NOTE:  "issueId" is the 'key identifier' and "statusId" is the 'key status' property in the above sample.

REST API POST URI sample format for Issue Tracking systems

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.

The POST data in configured in

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

NOTE:  For the branch name, SAM has a built in placeholder called 'source'. If there are additional data elements like version or repository, those can be configured by providing static elements.

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:

NOTE:  For readability only two fields are provided in the output.

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

Back to top