harmony api developers documentation (version 2.2)

Harmony API

Developers documentation

Version 2.2

Overview

• Harmony exposes all its functionality as a set of web services.

• JSON is the format of the messages, HTTPS is the transport.

• Basic authentication is used to authenticate all API calls or a token provided when user has previously logged in.

• All web services have a single end-point:– https://<domainname>/handler.yaws - when used with

security token– https://<domainname>/ws/handler.yaws – when used

with basic authentication

Message and response format

• An API call consists of URL parameters. These parameters can be simple strings or JSON formatted structures

• A response of an API call is always returned as JSON object. If it contains “exception” property, the call was unsuccessful. The lack of exception property signifies the success of the API call.

Exceptions• The returned JSON object contains the exception property {exception,

<exception_type>} and possibly some other information• Here is a list of the exceptions Harmony can return:

– not_authenticated : user is not authenticated to make this call– not_authorized: user is not authorized to perform the specified

action– dialog_already_submitted – has also dialog_id and key– dialog_withdrawn– has also dialog_id and key– search_query_invalid– key_not_found– dialog_name_not_found– harmony_down – Harmony is not responding– improper_event_format– no_facts_or_ref_objects– no_event_name– event_not_found– unkown_facts

Required parameters

• message - determines the operation of the web service to be executed; should appear in every API call

• token - security token – not needed for all messages; only required when using “token” authentication; not required when using basic authentication.

Types of messages

• Based on the authentication state of the user– (0) When no configuration is uploaded– (1) When user is not authenticated– (2) When config is uploaded and user is

authenticated– (3) If user is member of the Admin group

0. No config API calls

• When no configuration is uploaded, only these 3 calls are allowed:– get_all_lucidchart_diagrams– get_lucidchart_diagram– create_empty_config

• For all other API calls, Harmony would return {exception, no_config}

• If configuration is present but still one of these three calls are performed, Harmony will return no_token, not_authenticated or config_present exception depending whether the user is already authenticated or not.

No config API calls

get_all_lucidchart_diagrams

• Description: This call will ask Harmony to start a OAuth communication with LucidChart.com for retrieving the user’s diagrams.

• Input parameters:– No additional parameters other than the default

“message”• Response: The URL to redirect the browser

to. This is the OAuth page of LicidChart.com Web service where the user should enter the credentials.

get_all_lucidchart_diagrams

get_lucidchart_diagram

• Description: This call will ask Harmony to start a OAuth communication with LucidChart.com for retrieving a specific user diagram. If successful, the diagram will be converted to Harmony’s configuration. Then Harmony will start a OAuth communication with Google. After receiving permission, a new spreadsheet document with the same name as the diagram will be generated in the user’s Google account. The configuration will be uploaded to Harmony and will populate the spreadsheet.

• Input parameters:– diagram_id – the LucidChart.com identification of the diagram.

• Response: The URL to redirect the browser to. This is the OAuth page of LicidChart.com Web service where the user should enter the credentials.

get_lucidchart_diagram

create_empty_config

• Description: With this API call, Harmony will start a OAuth communication with Google. After receiving permission, a new spreadsheet document with the supplied name will be generated in the user’s Google account. The configuration will be uploaded to Harmony. This configuration contains an example dialog “test dialog” and an example rule.

• Input parameters:– config_name – the name of the Google spreadsheet that

will be created.• Response: The URL to redirect the browser to. This is

the OAuth page of Google documents .Web service where the user should enter the credentials.

create_empty_config

1. Not authenticated API calls

• Two calls are allowed when (a) user is not authenticated, but (b) there is a configuration uploaded:– get_public_token– login

• All other calls will fail with {exception, not_authenticated} or {exception, no_token}

get_public_token

• Description: This call will try to get a public token for accessing the public resources Harmony provides. This is usually done on page load. Note that if there are no public resources, Harmony will return {exception, not_authenticated}.

• Input parameters:– No additional parameters required.

• Response: JSON object, containing:– token – the newly generated public token

get_public_token

login• Description: Sent when user tries to authenticate. Harmony supports four

forms of authentication: through OpenID (for Yahoo!, Aol or any other OpenID provider); through Facebook’s connect protocol; through OAuth for authentication with Twitter, Google and LinkedIn; and through the LDAP protocol.

• Input parameters– method– a predefined set of allowed methods:

• google• facebook• yahoo• aol• twitter• linkedin• opened

– url – specifies the url of the OpenID provider

• ldap– user– password

– request_page – the encoded URL of the page the user was on and where Harmony will redirect after successful login

• Response: For LDAP authentication, the token is returned. Otherwise, the user is redirected to the appropriate authentication page. Then the user is returned to “request_page” and the token is embedded in the URL as param.

login

2. User authenticated API calls

• These API calls expect a token param to be present. If no token is provided, {exception, no_token} is returned without further attempt to check the API call.

logout

• Description: Sent with request to logout the currently logged in user. The user’s token will be invalidated.

• Input parameters: Default parameters only

• Result: the token will be invalidated

logout

get_dialog_names

• Description: Retrieves the list of business events. They are all represented as dialogs. The result is an array of business event names. The name can then be used to retrieve the event definition for example. Can also contain the dialog title – what should be presented to the end user. Read-only operation.

• Input parameters: Default parameters only.• Response: JSON array “dialog_names” containing JSON

objects with properties:– name – this should be used in further API calls to identify this

particular dialog– title – a title to display to the user (might be missing). It is

language dependent.• Possible exceptions: not_authenticated

get_dialog_names

get_work_items

• Description: Retrieves all outstanding work items (dialogs) from all work queues. Read-only operation.

• Input parameters: Default parameters only.• Response: JSON array “work_items” containing JSON objects with

properties:– case_id - the Case ID to which each work items belongs to;– dialog_id - each dialog instance has a unique identifier;– dialog_name - matches one of the business event names retrieved with

a get_dialog_names call;– queue - the work queue name, can be either a user or a group work

queue;– index - information from the case is indexed and displayed for

reference, in the example it is the relatie name;– dialog_title – optional, the title of the dialog that should be displayed

to the user• Possible exceptions: not_authenticated, not_authorized

get_work_items

get_case_ids

• Description: Requests the case ids of all the cases. Used when there is an item of type “case_id” so to fill the select with the returned keys. Read only operation.

• Input parameters: Default parameters only• Result: JSON array “case_ids” containing

strings.• Possible exceptions: not_authenticated

get_case_ids

submit_dialog

• Description: Once all values in a dialog are filled-in by the user, the dialog is submitted to Harmony. Harmony will then execute all business rules related and will enrich the case data for the case. This is an operation that changes data and state. Write only operation.

• Input parameters– Default parameters– payload - contains the message payload, in this case, the contents of the dialog to

be submitted to Harmony• dialog_name• dialog_id• case_id• facts

– concept– attrib– value

• Result: {success: true} or exception• Possible exceptions: not_authenticated, not_authorized,

improper_event_format, no_facts_or_ref_objects, no_event_name, event_not_found, unkown_facts, dialog_withdrawn, dialog_already_submitted

submit_dialog

submit_for_predictions

• Description: Used to send data the moment the user enters it so to show prediction from the firing of rules. Write only operation.

• Input parameters:– Default parameters;– payload – in the same format as with

submit_event• Result: {success: true} or exception• Possible exceptions:– same as submit_event call

submit_for_predictions

get_predictions

• Description: After a “submit_for_predictions” call, get_predictions is sent to collect the outcome of the predict data. Read only operation.

• Input parameters:– Default parameters– case_id – identifies the case we want to get prediction

for• Result: JSON object

– case_id – identifies the case the data belongs to– facts – JSON array of facts – see Facts array slide

• Possible exceptions: not_authenticated, not_authorized

get_predictions

get_dialog

• Description: Retrieves the definition of the business event, as well as all the related case data for it . Read-only operation.

• Input parameters:– Default parameters– name - the name of the event, from a call to get_dialog_names.– case_id – (optional) the case id, as retrieved with a call to get_work_items. If it is not present, only the

dialog definition will be retrieved without any preloaded data.– dialog_id – (optional) needed for retrieving outstanding work item (together with case_id)

• Response: JSON object:– name – the name of the dialog– contents – JSON array of dialog items

- concept – first part of the name of the dialog item- attrib – second part of the name of the dialog item- type - the dialog item type;- ext - in case the type is multiple_choice, the variable contains the list of possible options;- value - "undefined" means that the values is still not set for this case;- can_override - if "yes", the item can be overridden by the user (by default once a pair has a value, it is disabled and

cannot be changed);- lookup – whether the item is a key of a reference data- lookup_source – where to look for the corresponding reference date- required – whether this dialog item is required to be filled in;- initial_state – whether the item should be initially hidden- description – a description of the item, presented instead of the c/a pair

• Possible exceptions: not_authenticated, not_authorized, dialog_withdrawn, dialog_already_submitted, dialog_name_not_found, key_not_found

get_dialog

get_case_data

• Description: Retrieves all case data for the case. Read-only operation. Note that it returns a list because all children will be returned in separate objects.

• Input parameters– Default parameters– case_id - determines the case for which case data will be

retrieved;• Response: JSON array of JSON objects containing:

– case_id - determines the case for which case data is retrieved

– facts – JSON array – see Facts array slide• Possible exceptions: not_authenticated,

not_authorized, key_not_found

get_case_data

get_case_history

• Description: Retrieves history for a specific case. Read only operation.• Input parameters:

– Default parameters– case_id – identifies the case we want to get history for

• Result: the JSON object “case_history” containing JSON array of JSON objects with properties:– case_id – case identifier– dialog_id – internal event reference number– dialog_name – the name of the dialog– queue – who must handle the dialog (or already did)– because – reason why the dialog was asserted. this is an object. same as in

fact object– asserted_on – (optional) when the dialog was asserted– done_on – (optional) when the dialog was submitted– who – (optional) – submitted by who

• Possible exceptions: not_authenticated, not_authorized

get_case_history

get_facts_for_history_record

• Description: Retrieves the facts that where submitted with a specific dialog. Read only operation.

• Input parameters:– Default parameters– case_id – identifies the case – dialog_id – identifies the dialog that submitted the facts

• Result: the JSON object “facts” containing JSON array of JSON objects with properties same as described in Facts array slide

• Possible exceptions: not_authenticated, not_authorized

get_facts_for_history_record

search

• Description: Searches for criteria in the submitted data. Read only operation.

• Input parameters:– Default parameters– criteria – the search criteria

• Result: JSON object:– criteria – the search criteria– hits – how many results we have in the array– time_it_took – the milliseconds needed for lucene to find the data– results – JSON array of JSON objects:

• case_id – identifies the hit is for which case• text – the text that contains the hit• score – lucene score of how close the match is to the creteria

• Possible exceptions: not_authenticated

search

get_meta_info

• Description: Gets information for the currently logged in user and the uploaded configuration. Read only operation.

• Input parameters: Default parameters only• Result JSON object:

– name – as defined in Excel configuration– username – as defined in Excel configuration– email – as defined in Excel configuration– groups – the groups the user belongs to

• Possible exceptions: not_authenticated

get_meta_info

test_predictions

• Description: submits facts to Harmony and gets the predictions (outcomes) of the fired rules. The original facts are also returned, e.g. the whole case data.

• Input parameters:– facts: JSON array containing fact objects. same as

get_predictions• Result JSON object: same as the result from

get_predictions. Note that case_id will be equal to “test_outcome” for every call.

• Possible exceptions: not_authenticated

test_predictions

get_reference_data

• Description: searches for “term” in the reference data, specified in “concept” and “attrib”. The results are returned and should be shown to the user to choose from them.

• Input parameters:– concept – the concept of the reference key item for which we perform the search. This

corresponds to the name of the reference object– attrib – the attribute of the reference key item for which we perform the search. This

corresponds to the name of the reference key.– case_id – context param – the case id of the current case– dialog_id – context param – the dialog id of the current dialog (on which the dialog item

(reference key) is present)– dialog_name – context param – the name of the current dialog (on which the dialog item

(reference key) is present)– term – the search term

• Result JSON object “reference_data” with the following properties:– object – the name of the reference object. the same as “concept” param– keys – an array of the matches reference keys

• name – the name of the reference key. same for each result. same as “attrib” param• value• attributes – an array of reference attributes corresponding to this reference key

– name– value

• Possible exceptions: not_authenticated

get_reference_data

get_correlation_data

• Description: this API call tries to find a case that contains the “term” in a “concept” / “attrib” pair. This way we can switch the case we are working on.

• Input parameters: same as in get_reference_data• Result JSON object “correlation_data” with the following:

– typed_key – an object, represents the dialog item the user typed in• concept• attrib• value

– additional_parts – an array of objects of form typed_key if the correlation_key is made of multiple parts

– filled_items – an array, dialog items that have values in the case we are switching to• concept• attrib• value

– case_id – the case id we have to switch context to• Possible exceptions: not_authenticated

get_correlation_data

Facts array of JSON objects

• Returned by get_predictions.• Each element contains the following properties:

– concept– attrib– value– queue (optional)– because (optional)

• concept• attrib• op• value

– is_ref

3. Admin user API calls

• If user is authenticated and is member of the Admin group, the following API calls are allowed to be performed.– flush– get_config– get_version– get_reference_objects_names– get_reference_object– ref_attrib_update– ref_key_update

• If these calls are tried from a user who doesn’t belong to the Admin group, Harmony will return {exception, not_authorized}

flush

• Description: Flushes the loaded configuration.

• Input parameters: only the default ones

• Result: {success, true} or exception• Possible exceptions:

not_authenticated, not_authorized

flush

get_config

• Description: Returns XML representation of the uploaded configuration.

• Input parameters: only the default ones

• Result: XML of the configuration• Possible exceptions:

not_authenticated, not_authorized

get_version

• Description: Retrieves the configuration version. It is visible in the Google spreadsheet, under Config sheet. This version is also inserted in a new case when it is created. When the configuration is updated and uploaded to Harmony, Harmony increments the version number if it detects changes in the rules and dialogs.

• Input parameters: only the default ones• Result: {config_version: N} – N is the version

number• Possible exceptions: not_authenticated,

not_authorized

get_version

get_reference_objects_names

• Description: Retrieves the names of the reference objects found in the currently uploaded configuration.

• Input parameters: only the default ones• Result: JSON object with property

“reference_objects_names” that is a JSON array containing string names of reference objects.

• Possible exceptions: not_authenticated, not_authorized

get_reference_objects_names

get_reference_object

• Description: Retrieves a whole reference object, all its keys and attributes.

• Input parameters:– name – the reference object name to retrieve

• Result: A JSON object containing the following properties:– possibleAttributes – an array of objects with a single property

“name”. These are the possible attributes a reference object can contain. Note that not all keys will have all attributes.

– keyName – the reference key name– object – the name of the reference object – sent in the name

parameter– keys – the reference keys as described in get_reference_data API

call• Possible exceptions: not_authenticated, not_authorized,

ref_object_not_found

ref_attrib_update

• Description: Updates a single reference attribute for a particular reference key. The update is propagated to the source of the reference data, e.g. Google spreadsheet.

• Input parameters:– object_name – the name of the reference object– key_val – the value of the reference key the updating reference

attribute is member of– attrib_name – the name of the updating reference attribute– new_val – the new value for the reference attribute

• Result: {success, true}• Possible exceptions: not_authenticated, not_authorized,

ref_object_not_found, ref_key_not_found

ref_attrib_update

ref_key_update

• Description: Allows updating a the whole reference key – all or any of its attributes. Note that it is not possible to update the value of the reference key. If a new value is provided for the reference key, a whole new reference key will be created. A common scenario is to search for existing reference key, change its value and possibly some of the attributes and to add it. This way the reference key is duplicated.

• Input parameters: – object_name – the name of the reference object– payload – JSON object

• key – JSON object representing the reference key– name– value

• attributes – JSON array containing JSON objects representing reference attributes– name– value

• Result: Object with properties:– success – with value “true”– status – with value either “updated” or “added”

• Possible exceptions: not_authenticated, not_authorized

ref_key_update