RPC Services

Get form URL for user

Description

This endpoint returns a URL that may be used one time to access a form or flow, authenticated as the specified user. While authenticated as an administrator, this can be for any user on the domain. For other users, it can only function when used to produce a URL bound to their own user account.

Request

GET or POST /liveforms/api/getFormLinkForUser

Parameter	Description
domain	The name of a valid domain which the authenticated user has access to.
appId	The id of an application in the domain.
formId	The request must include one of either formId or flowId. The id of the requested form.
flowId	The request must include one of either formId or flowId. The id of the requested flow.
user	The name of the user that the URL should be produced for.

Example JSON request

{
   "domain": "demo",
   "appId": "1",
   "formId": "1",
   "user": "user1"
}

Example XML request

<?xml version="1.0" encoding="UTF-8"?>
<request>
    <domain>demo</domain>
    <appId>1</appId>
    <formId>1</formId>
    <user>user1</user>
</request>

Response

Possible HTTP response codes:

Code	Description
200 OK	Success
400 BAD REQUEST	The specified domain, application, form, flow, or user may not exist.
401 UNAUTHORIZED	The username/password used for authentication was invalid.
403 FORBIDDEN	The authenticated user does not have permission to generate a URL for the specified user.
500 SERVER ERROR	The request failed due to an internal server error.

If the request is successful, a JSON (default) or XML payload will be returned containing the requested information.

Example JSON response

{
   "formLinkForUser": "/liveforms/path/of/form/url?token=abc123",
   "link": [{
      "rel": "formLinkForUser",
      "href": "/liveforms/path/of/form/url?token=abc123"
   }]
}

Example XML response

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <formLinkForUser>/liveforms/path/of/form/url?token=abc123</formLinkForUser>
   <link rel="self" href="/liveforms/path/of/form/url?token=abc123"/>
</response>

Get list of forms/flows for user

Description

This endpoint returns the list of forms and/or flows a specified user has access to. This requires an administrator account, either a system superadmin or a domain admin for the requested domain.

Request

GET or POST /liveforms/api/getFormListForUser

Parameter	Description
domain	The name of a valid domain which the authenticated user has access to.
user	The name of the user whose accessible forms/flows should be listed.
type	Optional. One of form, flow, or both. Defaults to both if omitted.

Example JSON request

{
   "domain": "demo",
   "user": "user1",
   "type": "both"
}

Response

Possible HTTP response codes:

Code	Description
200 OK	Success
400 BAD REQUEST	A required parameter (domain, user) is missing, or type is not one of form/flow/both.
401 UNAUTHORIZED	The username/password used for authentication was invalid.
403 FORBIDDEN	The authenticated user is not a system superadmin or a domain admin for the requested domain.
404 NOT FOUND	No matching forms/flows were found for the specified user.
500 SERVER ERROR	The request failed due to an internal server error.

If the request is successful, a JSON (default) or XML feed is returned in the same style as the Forms and Flows list endpoints.

Get server version

Description

This endpoint returns the API version as plain text. It uses the same Basic HTTP Authentication as the rest of the REST API.

Request

GET /liveforms/api/version

Response

A 200 OK response with a plain-text body.

Note

This currently always returns the literal text 1.0 and does not reflect the installed LiveForms release version (for example 1.5.13). Do not rely on this endpoint to determine the running product version.

Start a flow instance

Description

This endpoint starts a new instance of a flow, optionally pre-filling form field values for the first step. The authenticated user must have at least some permission on the flow’s application, and either Manage rights on the application or Manage/Design rights on the flow itself - a user with Design on the flow but no permission at all on its containing application is still rejected.

Request

GET or POST /liveforms/api/initFlow

Parameter	Description
domain	The name of a valid domain which the authenticated user has access to.
flowId	The id of the flow to start.
data	A map of control name to value, used to pre-fill fields on the flow’s first step. A key ending in .file is treated as a base64-encoded file upload rather than a text value.

Example JSON request

{
   "domain": "demo",
   "flowId": "1",
   "data": {
      "FirstName": "Jane",
      "LastName": "Doe"
   }
}

Response

Possible HTTP response codes:

Code	Description
200 OK	Success. The response body is the plain text 200 OK, not a JSON/XML payload.
403 FORBIDDEN	The authenticated user has no permission at all on the application, or lacks both Manage on the application and Manage/Design on the flow.
404 NOT FOUND	The specified flow does not exist, or has no published process definition.
500 SERVER ERROR	The request failed due to an internal server error.

Jenzabar Portal API

Description

A single-purpose endpoint used for the Jenzabar Portal integration. Unlike the rest of the REST API, the target domain is not part of the request - it is always the domain configured in Target Tenant (Domain) under Configuration’s Jenzabar Portal Configuration section (the system default is domain d). The authenticated user must be a superadmin, or a domain admin for that configured domain.

Request

POST /liveforms/api/portal

Parameter	Description
act	Required. One of login, logout, update, or getlist.
form	Required for login. The name of a form/flow to link to, or tasklist for the user’s task list.
name	Required for login, logout, and update. The LiveForms username.
firstname, lastname, email, pass, role	Optional for login; required together for update. role is a comma-separated list of role names. Only applied if Manage/Create Users (and, for new roles, Auto-Create Roles) is enabled for the Jenzabar domain.

act=login: Returns a one-time link to the requested form/flow/task list for the given user (creating the user, and any roles named in role, if user auto-creation is enabled and the user doesn’t already exist). The response body is the plain-text URL, not JSON/XML.

act=logout: Currently a stub - it validates that name was provided and returns 200 OK, but does not invalidate any session.

act=update: Creates or updates the named user’s profile fields and role list, if user auto-creation is enabled.

act=getlist: Returns a JSON object listing every published form and flow in the configured domain, e.g. {"forms": [{"formName": "...", "formDesc": "..."}, ...]} (despite the key name, this list includes both forms and flows, with no field to tell them apart).

Response

Possible HTTP response codes:

Code	Description
200 OK	Success.
400 BAD REQUEST	act is missing/invalid, a required parameter for that action is missing, or (for login/update) the named user does not exist and user auto-creation is disabled.
401 UNAUTHORIZED	The username/password used for authentication was invalid.
403 FORBIDDEN	The authenticated user is not a superadmin or a domain admin for the configured Jenzabar domain.
500 SERVER ERROR	The request failed due to an internal server error.