Workspaces Group API

The Group API provides a REST service for querying Form and Job Groups in Journey Manager in a secure and efficient manner.

Security

To access the Workspaces REST endpoint the caller needs to pass through Spring Security Session Management. First the user has to be authenticated with the Workspaces configured security manager. The user may authenticate via a login page or via Single Sign-on such as ADFS, oAuth2 or custom SSO.

The result of the API calls is subject to the user security policy.

URL Endpoint

The Workspaces Group API URL endpoint is as follows:

``` https:///workspaces/secure/api/v1/group ```

Service API

---

This section provides a description all the Group API operations including:

• POST Query Group

POST Query Group

Returns a list of job and form groups filtered on the specified criteria.

The result will be ordered alphabetically by group name.

URL Format

POST https://<tm server>/workspaces/secure/api/v1/group/query

POST Body

The POST request must contain a JSON structure describing the group query. To support multiple parameters this API uses the HTTP Content Type: application/json

The set of query JSON attributes is listed below (all attributes are optional unless indicated otherwise):

Attribute	Type	Description
fetchLimit	Integer	Specifies the fetchLimit of the query and is the max number of results returned. Default value is applied if fetchLimit entered is greater than 10,000. Default value is 10,000 (required)
fetchOffset	Integer	Specifies fetchOffset of the query. Returns (fetchOffset + fetchLimit) number of results starting from the fetchOffset index. Default value is 0 (optional)
filters	List	Provides a list of filters to query groups by. For more details on how to define the filters, see Filters (optional)

Supported Criteria Attributes

The criteria attributes supported are listed below. Any additional attributes will return a Bad Request Response.

Criteria Attribute	Type	Supported Operators	Description
groupName	String	=, IN, LIKE	Filter groups based on the name
groupType	String	=	Filter groups based on the type. Group types are 'Form' or 'Job'

Example: Query Group

Please ensure you specify Content-Type: application/json

POST <b>/workspaces/secure/api/v1/group/query</b> HTTP/1.1
Host: https://transact.workspaces.com
Content-Type: application/json

{
    "fetchLimit": 100,
    "fetchOffset": 0,
    "filters": [
        {
            "criteria": [
                "groupName LIKE 'job'",
                "groupType = {0}"
            ],
            "params": [
                "Form"
            ],
            "operator": "AND"
        },{
            "criteria": [
                "groupName LIKE 'App'"
            ],
            "operator": "AND"
        }
    ]
}

200 Response

{
    "fetchLimit": 100,
    "fetchOffset": 0,
    "durationMs": 3,
    "result": [
        {
            "name": "Job Applicants",
            "description": "Job Applicants",
            "type": "Form"
        }
    ]
}

More examples

Complex queries can be created from joining multiple criterias using "AND" or "OR" operators.
For examples on how define these queries, see Filters

Error Messages

Error Key	Error	Error Code
illegalArgument	Unsupported criteria attribute: <attribute> Unsupported operator for attribute '<attribute>': <Operator> For input string: <string> Please see Error Log ID {number}	400 - Bad Request
internalError	Please see Error Log ID {number}	500 - Internal Server Error
unableToResolvePortal	Unable to resolve portal from request	400 - Bad Request

Error Responses

400 - Bad Request

Bad request or request parameter. Check error message for details.

404 - Not Found

Ensure the URL endpoint is entered correctly.

500 - Internal Server Error

Exception occurred in group query. Contact administrator.