Programming the push API

Introduction

Many organizations prefer to use Yomly as the reference source of information about their employees and HR processes. You might require one-way synchronization of data. For example, you might want to:

• Update Active Directory (AD) with new employee information
• Transfer payment information to Oracle GL.
• Update Microsoft Outlook with calendar information related to Yomly activities.

To enable these types of transfers, Yomly implements a simple publish/subscribe model in which events from within Yomly are packaged and sent to a queue. A client program can then read this queue and perform the required tasks on a remote system. Unlike the Yomly REST API and GraphQL APIs, this push mechanism is read-only with respect to Yomly data.

Objective

In this tutorial, you will learn how to program the Yomly push API.

Procedure

To program the push API, do the following:

1. Define an API user. This step is performed by our Professional Services team.

2. Define a queue. This step is also performed by our Professional Services team.

3. Activate the push API. You can do this by updating the API preferences in the platform settings. Do the following:

   1. In the sidebar, in the Business section, click Settings.

   2. Go to the Preferences tab.

   3. Click API to expand the section.

   4. Click the name of the push API (for example, Employee-Push-API) to view the preferences that you can set.

   5. Select the enabled checkbox.

   6. In queue, enter the name of the queue created in step 2.

   7. Click Save.

Client Code

The following code snippet illustrates the basic structure of a Python client to access the queue:

import boto3

def getMessage(sqs):
    # Receive message from SQS queue
    response = sqs.receive_message(
        QueueUrl=queue_url,
        AttributeNames=[
        'SentTimestamp'
        ],
        MaxNumberOfMessages=1,
        MessageAttributeNames=[
         'All'
        ],
        VisibilityTimeout=0,
        WaitTimeSeconds=0
)

    message = response['Messages'][0] # message is received as a JSON object here

def deleteMessage(message):
    receipt_handle = message['ReceiptHandle']  # grab the handle so we can delete the message once processed
    sqs.delete_message(
     QueueUrl=queue_url,
     ReceiptHandle=receipt_handle
    )

def processMessage(message):
    type = message["transactionType"]
    # process the message here in whatever way you want

if __name__ == '__main__':
    # Create SQS client
    sqs = boto3.client('sqs')
    queue_url = 'iMile_Transaction_Queue'
    message = getMessage(sqs)
    processMessage(message)
    deleteMessage(message)

Queue Data Structures

The messages delivered to the queue are formatted as JSON messages. The formalization of these messages into JSON schema definitions is ongoing. However, the eventual schemas will be backward-compatible with the descriptions in the following table.

Queue messages are built around the structure of workflow events and the data formats are interchangeable between workflow usage and queue formats. In fact, the queue is populated via a global workflow that responds to the published global event.

The Queue Activity task minimally processes the information passed to it. If the user has activated the API, the task adds a message header to the information passed and simply adds it to the queue. This enables you to create arbitrary queue messages if you want to produce message types other than the ones catered by the native message types.

Message Attributes

The following elements are added to the data appended to the queue.

Objects

EmployeeData

The EmployeeData object contains the information of the employee that is the subject of the event.

A separate Employee object can be included to describe the employee that requested or initiated the event.

Status Object

Leave Request

Leave request messages are sent when a leave is requested, approved or cancelled.