WorkFlow RESTful API

287 Pages·2016·6.12 MB·English

Workflow RESTful API
Documentation
© 2018 SAP, Inc. All Rights Reserved.
Contents

Contents ........................................................................................................................................... 1
Introduction ..................................................................................................................................... 4
Authentication ................................................................................................................................. 5
Entity Beans ..................................................................................................................................... 7
Complete and Simple Bean .......................................................................................................... 7
Setting Entity’s child beans .......................................................................................................... 9
Searching entities ....................................................................................................................... 10
Limiting attributes returned in search ....................................................................................... 11
Returning errors with messages ................................................................................................ 12
Date and Date Time Bean attributes .......................................................................................... 13
Number and Decimal Bean attributes ........................................................................................ 13
Reading Custom Field values ...................................................................................................... 14
Setting Custom Field values ....................................................................................................... 17
Custom Field formats ............................................................................................................. 18
Length options ....................................................................................................................... 24
Entity Beans listing ..................................................................................................................... 27
HTTP response codes ..................................................................................................................... 37
APIs Listing ..................................................................................................................................... 38
Account ...................................................................................................................................... 39
Case ............................................................................................................................................ 40
Case Type ................................................................................................................................... 44
Company .................................................................................................................................... 45
Contact ....................................................................................................................................... 46
Custom Field............................................................................................................................... 47
Custom Table ............................................................................................................................. 48
1 Workflow API © 2018 SAP, Inc. All Rights Reserved.
Department ................................................................................................................................ 49
Message ..................................................................................................................................... 50
Project ........................................................................................................................................ 51
User ............................................................................................................................................ 52
User Type ................................................................................................................................... 53
Detailed Workflow API ................................................................................................................... 54
Account ...................................................................................................................................... 54
Case ............................................................................................................................................ 67
Case Type ................................................................................................................................. 175
Company .................................................................................................................................. 179
Contact ..................................................................................................................................... 185
Custom Field ............................................................................................................................ 195
Custom Table ........................................................................................................................... 202
Department .............................................................................................................................. 224
Message ................................................................................................................................... 229
Project ...................................................................................................................................... 234
User .......................................................................................................................................... 244
User Type ................................................................................................................................. 254
Appendix A – Countries ................................................................................................................ 259
Appendix B – States ..................................................................................................................... 265
Appendix C – Custom Field Types ................................................................................................ 267
Appendix D – Error Codes ............................................................................................................ 268
Appendix E - Workflow API Overview .......................................................................................... 270
Account .................................................................................................................................... 270
Case .......................................................................................................................................... 270
Case Type ................................................................................................................................. 272
Company .................................................................................................................................. 272
Contact ..................................................................................................................................... 272
Custom Field............................................................................................................................. 272
Department .............................................................................................................................. 273
Message ................................................................................................................................... 273
2 Workflow API © 2018 SAP, Inc. All Rights Reserved.
Project ...................................................................................................................................... 274
User .......................................................................................................................................... 274
User Type ................................................................................................................................. 274

3 Workflow API © 2018 SAP, Inc. All Rights Reserved.
Introduction

The Workflow RESTful Service API (further referenced as Workflow API) is intended to allow third
party applications to collaborate with Workflow. Workflow API enables its consumers to easily
perform various operations over Workflow objects using standard HTTP methods: GET, POST,
PUT and DELETE.

HTTP methods are used in this way:

1) GET – retrieve an entity
2) POST – create a new entity
3) PUT – update an entity
4) DELETE – delete an entity

For the call to be successfully completed user performing an API call must be authenticated.

Note: In order to easily try out the examples from this document you can use Google Chrome’s
“Postman – Rest Client” extension, Mozila Firefox’s “RESTClient” add on or any other similar
product. We recommend Google Chrome’s extension “Postman – Rest Client” which has a lot of
options including call history, favourite calls, support for authorization, support for uploading
files etc.
4 Workflow API © 2018 SAP, Inc. All Rights Reserved.
Authentication

Each Workflow API request must be authenticated. Two request headers are required in reach
request in order to authenticate the user performing an API call:
1) Authorization header
Workflow API uses Basis Authentication mechanism with standard HTTP headers which
means that no handshakes have to be done. User performing Workflow API call must
be a Workflow user with admin rights. Username used for Workflow API authentication
is user’s login name and password is user’s WS Token which can be found in Setup ->
Users -> Users -> Edit specific user.

The Authorization header is constructed as follows:
1. Username and WS Token are combined together using semicolon into a
string "username:WsToken".
2. The resulting string is then encoded using Base64 encoding.
3. The authorization method and a space "Basic " is then put before the
encoded string.

Example: For user with login name “jsmith” and WSToken “0mr3ot99LYMvit77J9sf”
Authorization header will look like this:
Authorization: Basic anNtaXRoOjBtcjNvdDk5TFlNdml0NzdKOXNm

Java code example for creating Authorization header looks like this:

String userName = "jsmith";
String wsToken = "0mr3ot99LYMvit77J9sf";
String nameToken = userName + ":" + wsToken;
byte[] encodedBytes = Base64.encodeBase64(nameToken.getBytes());
String encoded = new String(encodedBytes); // anNtaXRoOjBtcjNvdDk5TFlNdml0NzdKOXNm
String headerValue = "Basic " + encoded;
String header = "Authorization: " + headerValue;
System.out.println(header); // Authorization: Basic anNtaXRoOjBtcjNvdDk5TFlNdml0NzdKOXNm

C# code is very similar and would look like this:

byte [] bytesToEncode = Encoding.UTF8.GetBytes("jsmith:0mr3ot99LYMvit77J9sf");
String encodedText = Convert.ToBase64String(bytesToEncode); // anNtaXRoOjBtcjNvdDk5TFlNdml0NzdKOXNm
…
5 Workflow API © 2018 SAP, Inc. All Rights Reserved.
2) domain header
Domain header will tell Workflow to which domain does the API call refer to. On example,
domain header might look like this:
domain: Workflow_api_test
If user performing API call cannot be identified 403 Forbidden status will be returned.
6 Workflow API © 2018 SAP, Inc. All Rights Reserved.
Entity Beans

Each Workflow entity (case, account, contact, user etc.) has it’s Bean representation which
contains entity’s attributes. Beans are used to transfer data between requestor and Workflow.
Here is what you need to know about Entity Beans before starting to use Workflow API.

Complete and Simple Bean
Each entity has it’s complete and simple bean representation. Complete entity Bean is returned
when that same entity is requested and simple Bean representation is used when the entity exists as a
child entity of some other entity Bean.
On example, Contact Bean has “account” attribute and when Contact is returned it contains all
information about contact and simplified account field representation.
Example of complete AccountBean

GET /accounts/account_b

Response body:

{
"billing_address": {
"address2": "Fake Street 456",
"address3": "Third Street 100",
"city": "San Francisco",
"country": {
"name": "USA",
"system_id": "usa"
},
"state": {
"name": "California",
"system_id": "CA"
},
"street": "Some Street 123",
"zip": "12345"
},
"custom_fields": [
{
"name": "Day Went Live",
"system_id": "day_went_live",
"type_name": "Date",
"type_system_id": 3,
"value": "10/01/13",
"value_formatted": "01/10/13"
}
],
"description": "This is Account B.",
"employees": "500",
7 Workflow API © 2018 SAP, Inc. All Rights Reserved.
"fax": "555-555-777",
"location": "San Francisco",
"name": "Account B",
"phone": "555-555-777",
"shipping_address": { "address2":
"Fake Street 456", "address3":
"Third Street 100", "city":
"San Francisco", "country":
{
"name": "USA",
"system_id": "usa"
},
"state": {
"name": "California",
"system_id": "CA"
},
"street": "Some Street 123",
"zip": "12345"
},
"system_id": "account_b",
"uri": "http://localhost:8080/wpm/api/accounts/account_b",
"web_site": "www.accountb.com"
}

We can see that the complete AccountBean contains more than 10 attributes.

Contact is requested via GET /contacts/jsmith_someaddress_com. Contact contains simple
representation of AccountBean which only has three attribures (name, syste_id and uri).
GET /contacts/jsmith_someaddress_com

Response body:

{
"account": {
"name": "Account B",
"system_id": "account_b",
"uri": "http://localhost:8080/wpm/api/accounts/account_b"
},
"active": true,
"address": {
"address2": "Second Street 456",
"address3": "Third Street 789",
"city": "San Francisco",
"country": {
"name": "USA",
"system_id": "usa"
},
"state": {
"name": "California",
"system_id": "CA"
},
"street": "First Street 123",
"zip": "12345"
},
"cell_phone": "555-555-456",
"custom_fields": [
{
"name": "Contact Role",
"system_id": "contact_role",
"type_name": "Checkbox",
"type_system_id": 8,
8 Workflow API © 2018 SAP, Inc. All Rights Reserved.
"value": "Consultant",
"value_formatted": "Consultant"
}
],
"department": "",
"email": "[email protected]",
"fax": "555-555-741",
"first_name": "John",
"home_phone": "555-555-789",
"id": 1894,
"job_title": "Developer",
"last_name": "Smith",
"middle_name": "",
"name": "John Smith",
"phone": "555-555-123",
"system_id": "jsmith_someaddress_com",
"uri": "http://localhost:8080/wpm/api/contacts/jsmith_someaddress_com"
}

Setting Entity’s child beans
When an Entity is requested via GET method Workflow API returns complete entity with its child
entities as simple beans. When a new Entity is created via POST method or updated via PUT method,
entity’s child bean is set by sending child’s system id which is set as parents attribute.
On example, contact has “account” attribute which is used do display data about account when
certain contact is requested. On the other hand, when contact is created/updated we use
contact’s attribute “account_system_id” to set the account to contact.
The other example is CaseBean which uses “owner_system_id”, “contact_system_id”,
“project_system_id” and other similar Bean attributes to set case owner, contact, project etc.
Example for setting account while creating a new contact:

POST /contacts

Request body:

{
"account_system_id": "account_b",
"active": true,
"cell_phone": "555-555-111",
"custom_fields": [
{
"systemId": "contact_role",
"value": "consultant"
}
],
"department": "",
"email": "[email protected]",
"first_name": "John",
"home_phone": "555-555-987",
"job_title": "Developer",
"last_name": "Smith",
"phone": "866.612.7312"
}
9 Workflow API © 2018 SAP, Inc. All Rights Reserved.