Skip to main content
Kinetic Community

Fulfillment API Documentation

The Fulfillment API was written to make it easier to retrieve and modify information for Work Orders within the Fulfillment package. It is meant to be installed alongside a working version of the installment package.

Structure of the REST API

The REST API url follows the form of http://{server}.com/kinetic/DisplayPage?name={Service Item for API}&call={endpoint}. A sample API call is:

https://demo2.kineticdata.com/kinetic/DisplayPage?name=Fulfillment-API&call=/api/v1/groups

Time Zone Cookie

All calls made to any of the REST API endpoints need to include a time zone cookie for the call to be successfully completed. This time zone cookie is in the form of tz={time zone offset in minutes}. The value for the time zone offset will be the offset in minutes for a certain time zone while ignoring daylights savings time and multiplying in offset in minutes by -1.

Example Time Zone Cookies:

Pacific Time Zone: tz=480;

Central Time Zone: tz=360;

Eastern Time Zone: tz=300;

(Note: If API calls are returning a 200 code and an HTML page that says that cookies and/or javascript need to be enabled to use this application, it is very likely due to not having the tz cookie included in your Request Cookies.)

Endpoints

Authentication

/api/v1/auth/login

Logs in using a username/password combination and returns a cookie that will be used to authenticate the other API calls.

Methods: POST

Request Parameters: None

POST Payload: user, pass (required parameters are bolded)

{

    "user" : "Demo",

    "pass" : "pass123"

}

POST Response

{

    "cookie" : {

        "name" "JSESSIONID",

        "value" : {JSESSIONID value}

    }

}

 

/api/v1/auth/ping

Returns the auth endpoint that you are supposed to use to authentication against the rest of the API. 

Methods: GET

Request Parameters: None

GET Response

{

    "authType" : "login"

}

Assignment

/api/v1/assignment/groups

Returns all the children of the parent group provided including the name and number of children groups that are below each group. If the children count is 0, that means that it is the lowest group in the hierarchy and the group name can be used to search for what members are in the group using the /api/v1/assignment/members call. To traverse down the levels of groups, separate each level of group with double colons (::) when creating the parent parameter. For example, if your group hierarchy is Company => Organization => Group => Member, to search for a Group your parent parameter would be ?parent=Kinetic::Development to find all groups under a Company of Kinetic and an Organization of Development.

Methods: GET

Request Parameters: parent (required parameters are bolded)

?parent=Kinetic::US

GET Response:

[   

   {

        "name" : {Group Name},

        "childrenCount" : {# of child groups}

    }

]

 

/api/v1/assignment/members

Returns all the members that are included in the Group Name that is given in the request parameters.

Methods: GET

Request Parameters: group (required parameters are bolded)

?group={Group Name}

GET Response: 

{

    "count" : 1,

    "limit" : 0,

    "offset" : 0,

    "members" : {

        "fullName" : {Full Name},

        "loginId" : {Login Id},

        "firstName" : {First Name},

        "lastName" : {Last Name}

    }

}

Work Order

/api/v1/work-orders

Retrieves the work orders that correspond to the filter name that is supplied in the request parameters. An example filter name is Open Work Orders. This call also supports pagination and ordering through including the limit, offset, and order request parameters. Limit and offset can be any positive integers (ie. If you want page 3 and are returning 5 work orders per page, the correct limit and offset would be limit=5&offset=10). The order parameter needs a comma separated list of the field you want to sort by, followed by a ASC or DESC. These are the sortable fields: id, template, workOrder, requestedFor, requestedFor.name, requestedFor.loginId, assignee, assignee.name, assignee.loginId, originator.id, originator.source, status, due, details, summary, groups, submitType.

Methods: GET

Request Parameters: filter (required parameters are bolded), limit, offset, order

?filter={Filter Name}&limit=2&offset=2&order=modifiedDate DESC

GET Response: 

{

    "count' : 1,

    "limit" : 0,

    "offset" : 0,

    "workOrders" : {

        "id" : {Work Order Id},

        "workOrder" : {Work Order Name},

        "template" : {Template Name},

        "requestedFor" : {

            "name" : {The requested for user's name},

            "loginId" : {The requested for user's user id}

        }

        "assignee" : {

            "name" : {The assigned user's name},

            "loginId" : {The assigned user's user id}

        },

        "originator" : {

"id" : {The id of the original request that created this work order},

"source" : {The name of the original source that created this work order},

"url" : {The original source url, generated from the id and source}

        },

        "status" : {Work Order Status},

        "due" : {Due Date in ISO8601 form},

        "details" : {Work Order Details},

        "summary" : {Work Order Summary},

        "workOrderURL" : {Mobile web view for Work Order},

        "groups" : [

 

                {Group Name}

        ]

    }

}

 

/api/v1/work-orders/{id}

Returns all the fields for a single work order and the id for the work order is passed in the endpoint url.

Methods: GET

Request Parameters: None

GET Response:

{

        "id" : {Work Order Id},

        "workOrder" : {Work Order Name},

        "template" : {Template Name},

        "requestedFor" : {

            "name" : {The requested for user's name},

            "loginId" : {The requested for user's user id}

        }

        "assignee" : {

            "name" : {The assigned user's name},

            "loginId" : {The assigned user's user id}

        },

        "originator" : {

"id" : {The id of the original request that created this work order},

"source" : {The name of the original source that created this work order},

"url" : {The original source url, generated from the id and source}

        },

        "status" : {Work Order Status},

        "due" : {Due Date in ISO8601 form},

        "details" : {Work Order Details},

        "summary" : {Work Order Summary},

        "workOrderURL" : {Mobile web view for Work Order},

        "groups" : [

                {Group Name}

        ]

    }

 

/api/v1/work-orders/{id}/logs

Gets all the logs for the work order whose id is passed in the endpoint url. 

Methods: GET

Request Parameters: None

GET Response:

{

    "count' : 1,

    "limit" : 0,

    "offset" : 0,

    "logs" : {

        "id" : {Log Id},

        "type" : {Type of the Log},

        "createDate" : {Log Created Date in ISO8601},

        "loginId" : {The user that generated the log},

        "assigneeId" : {Id of the assigned user at the time of log creation},

        "entry" : {contents of the log entry}

    }    

}

 

/api/v1/work-orders/{id}/notes

GET: Retrieving the notes for a given work order based on the id passed to the endpoint url.

POST: Creating a new note for a given work order based on the id passed to the endpoint url. The POST object just needs to pass an "entry" field, which is the content of the note you want to create. 

Methods: GET,POST

Request Parameters: None

POST Payload: 

{

    "entry" : {Note content}

}

POST Response: 

{

    "id" : {Id of the newly created note},

    "created" : {Note created date in ISO8601},

    "modified" : {Note modified date in ISO8601},

    "loginId" : {Id of the submitting user},

    "entry" : {Content of the note}

GET Response: 

{

    "count" : 1,

    "limit" : 0,

    "offset" : 0,

    "notes" : {

        "id" : {Note id},

        "created" : {Note created date in ISO8601},

        "modified" : {Note modified date in ISO8601},

        "loginId" : {Id of the submitting user},

        "entry" : {Content of the note},

        "attachment" : {The attachment object (if present)}

    }

}

 

/api/v1/work-orders/{id}/assign

Assigning a group and/or member to a given work order based on the id that was passed to the endpoint url. All of the levels of group don't need to be assigned with an assign call, but all of the groups up until the lowest group you want to assign need to be specified. For example, if you have a hierarchy of Company => Organization => Group => Member and you want to assign a Group, you also need to include a Company and Organization.

Methods: POST

Request Parameters: None

POST Payload: 

{

    "group" : {Group Name},

    "member" : {Member User Id}

}

POST Response: Returns the Work Order object that the assignment was completed on.

See /api/v1/work-orders/{id}

 

/api/v1/work-orders/{id}/assign/me

Assigns the given work order based on the id in the endpoint url to the currently authenticated user. Currently, the automatic assignment can only happen if:

  • The currently logged in user is in exactly 1 group.
  • Every group level, except the final group and the member, must be already assigned.

If these conditions are met, assign me works the same as the normal assignment call with the exception that no POST object needs to be sent.

Methods: POST

Request Parameters: None

POST Payload: None

POST Response: Returns the Work Order object that the assignment was completed on.

See /api/v1/work-orders/{id}

 

/api/v1/work-orders/search

Allows you to search through open work orders based on the KSR (can be searched as either 12, KSR12, or KSR000000000012), the work order name or the assigned id. Returns a list of work orders similar to the /api/v1/work-orders call. This call also supports pagination and ordering through including the limit, offset, and order request parameters. Limit and offset can be any positive integers (ie. If you want page 3 and are returning 5 work orders per page, the correct limit and offset would be limit=5&offset=10). The order parameter needs a comma separated list of the field you want to sort by, followed by a ASC or DESC. These are the sortable fields: id, template, workOrder, requestedFor, requestedFor.name, requestedFor.loginId, assignee, assignee.name, assignee.loginId, originator.id, originator.source, status, due, details, summary, groups, submitType.

Methods: GET

Request Parametersquery (required parameters are bolded), limit, offset, order

?query={KSR/Assigned User Id/Work Order Name}

GET Response

{

    "count' : 1,

    "limit" : 0,

    "offset" : 0,

    "workOrders" : {

        "id" : {Work Order Id},

        "workOrder" : {Work Order Name},

        "template" : {Template Name},

        "requestedFor" : {

            "name" : {The requested for user's name},

            "loginId" : {The requested for user's user id}

        }

        "assignee" : {

            "name" : {The assigned user's name},

            "loginId" : {The assigned user's user id}

        },

        "originator" : {

"id" : {The id of the original request that created this work order},

"source" : {The name of the original source that created this work order},

"url" : {The original source url, generated from the id and source}

        },

        "status" : {Work Order Status},

        "due" : {Due Date in ISO8601 form},

        "details" : {Work Order Details},

        "summary" : {Work Order Summary},

        "workOrderURL" : {Mobile web view for Work Order},

        "groups" : [

                {Group Name}

        ]

    }

}

Filters

/api/v1/filters

The endpoint used to retrieve and add filters. 

Methods: GET, POST

Request Parameters: None

GET Response:

{

    "count" : 1,

    "limit" : 0,

    "offset" : 0,

    "filters" : {

        "name" : {Filter name},

        "qualification" : {A qualification compatible with the Work Order data source},

        "default" : {true/false}

    }

}

 

POST Payload:

{

    "name" : {Filter name},

    "qualification" : {A qualification compatible with the Work Order data source}

}

POST Response

{

        "name" : {Filter name},

        "qualification" : {A qualification compatible with the Work Order data source},

        "default" : {true/false}

}

 

/api/v1/filters/{name}

NOTE: The PUT and DELETE methods are accessed by using an X-HTTP-Method header. For example, to edit a filter using the PUT request, you will use a method of POST with this header included: X-HTTP-Method: PUT.

Methods: POST (X-HTTP-Method: PUT), POST (X-HTTP-Method: DELETE)

PUT Payload

{

    "name" : {New name for the current filter},

    "qualification" : {New qualification for the current filter}

}

PUT Response:

{

        "name" : {Filter name},

        "qualification" : {A qualification compatible with the Work Order data source},

        "default" : {true/false}

}

 

DELETE Payload:

None

DELETE Response:

None

Sources

/api/v1/sources

The endpoint used to retrieve and add sources. 

Methods: GET, POST

Request Parameters: None

GET Response:

{

    "count" : 1,

    "limit" : 0,

    "offset" : 0,

    "sources" : {

        "name" : {Source name},

        "url" : {A url used to get the original work order request when given an id}

    }

}

 

POST Payload:

{

    "name" : {Source name},

    "url" : {A url used to get the original work order request when given an id}

}

POST Response

{

        "name" : {Source name},

        "url" : {A url used to get the original work order request when given an id}

}

 

/api/v1/sources/{name}

NOTE: The PUT and DELETE methods are accessed by using an X-HTTP-Method header. For example, to edit a source using the PUT request, you will use a method of POST with this header included: X-HTTP-Method: PUT.

Methods: POST (X-HTTP-Method: PUT), POST (X-HTTP-Method: DELETE)

PUT Payload

{

    "name" : {New name for the current source},

    "url" : {New url for the current source}

}

PUT Response:

{

        "name" : {Source name},

        "url" : {A url used to get the original work order request when given an id}

}

 

DELETE Payload:

None

DELETE Response:

None