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.

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_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.
– 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.

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.
– 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.

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}.
– No additional parameters required.

• Response: JSON object, containing:
– token – the newly generated 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.

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

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_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_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.

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_ob
jects, no_event_name, event_not_found, unkown_facts, dialog_withdrawn, dialo
g_already_submitted

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.
– Default parameters;
– payload – in the same format as with
submit_event

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

get_predictions
• Description: After a “submit_for_predictions”
call, get_predictions is sent to collect the
outcome of the predict data. Read only
operation.
– 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

not_authenticated, not_authorized

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_na
me_not_found, key_not_found

get_case_data
• Description: Retrieves all case data for the case. Readonly operation. Note that it returns a list because all
children will be returned in separate objects.
• Input 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

not_authenticated, not_authorized, key_not_found

get_case_history
•
•

Description: Retrieves history for a specific case. Read only
operation.
Input 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_facts_for_history_record
• Description: Retrieves the facts that where
submitted with a specific dialog. Read only
operation.
– 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

search
• Description: Searches for criteria in the submitted data.
Read only operation.
– 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


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


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.
– 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.

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_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

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

get_config
• Description: Returns XML
representation of the uploaded
configuration.
• Input parameters: only the default
ones
• Result: XML of the configuration

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

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.

get_reference_object
• Description: Retrieves a whole reference object, all its keys
and attributes.
– 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

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.
– 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}
not_authenticated, not_authorized, ref_object_not_fo
und, ref_key_not_found

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
–
–

•

attributes – JSON array containing JSON objects representing reference attributes
–
–

•

name
value
name
value

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

•

Possible exceptions: not_authenticated, not_authorized

Harmony API developers documentation (version 2.2)

Recomendados

Recomendados

Más contenido relacionado

Destacado

Destacado (6)

Similar a Harmony API developers documentation (version 2.2)

Similar a Harmony API developers documentation (version 2.2) (20)

Más de 112Motion

Más de 112Motion (20)

Último

Último (20)

Harmony API developers documentation (version 2.2)