System Administrator Training

​

November 2022

​

1. Introduction to OpenFn & the Interoperability Solution
2. How the Solution Works

----------------------------------------------------

• OpenFn Administrator Basics
1. Managing Jobs
2. Monitoring Activity History
3. Errors & Notifications
• Admin Tools and Change Management
• Managing Users & Credentials
• Change Management Considerations

Agenda

​

Confidential Open Function Group UNICEF Project

Intro to OpenFn & �the V2 Interoperability Solution

OpenFn is a platform for workflow automation.

Systems �Sync

OpenFn provides scalable and secure infrastructure to connect technologies and automate key business and data exchange processes. It is sometimes referred to as an ”integration”platform or “middleware”.

Data Integration

Information Mediator

Business Process Logic

Audit Trail�& Routing

Security & Compliance

Automating case information sync with OpenFn...

OpenFn automates the on-demand referrals and decisions sync between the Oscar and Primero systems, securely exchanging children’s referral data between caseworkers .

V1 Solution:

1. Syncs ALL OSCaR cases with Primero for duplicate prevention
2. Syncs MoSVY referrals from Primero to OSCaR (1st referral only for each case)
3. Syncs Agency referrals from OSCaR to Primero (1st referral only for each case)

​

When case workers accept/reject referrals, decisions were not synced in the V1 solution.

V2 Upgrades:

• Syncs ALL OSCaR cases with Primero for duplicate prevention
• Syncs MoSVY referrals and decisions from Primero to OSCaR (multiple referrals for each case)
• Syncs Agency referrals and decisions from OSCaR to Primero (multiple referrals for each case)
• Syncs ‘risk level’ (new field)

Key Workflows

​

Sending referrals & �decisions (accept/reject)

Workflow 1: Sending case referrals to NGOs (Primero -> OSCaR)

Workflow 2: Sending case referrals to MoSVY (OSCaR -> Primero)

Flow 1: Primero -> Oscar Caseworker user experience...

Let’s log in...

https://demo-kh.primero.org/v2/login

​

Caseworker user:

Username: cw_banteay

Password: Primero2021

​

​

​

​

Confidential Open Function Group UNICEF Project

Primero user creates new Primero case & provides consent...

Primero user creates a service to send to OSCaR...

Note: OSCAR will not accept referrals without a Service Subtype selected

User refers service to OSCaR...

User specifies referral notes for OSCaR caseworker...

This automatically creates a referral record with status = ‘Pending’

Syncing to Oscar…

Confidential Open Function Group UNICEF Project

New case and referral is successfully sent to Oscar!

New case is ‘Accepted’ or ‘Exited’ in Oscar…

… this decision automatically appears on the first referral form.

Jean Clause

After OpenFn syncs, decision will be reflected in Primero referrals and services

Referrals

Services

New 2nd referral is sent to Oscar

New 2nd referral is Accepted or Exited in Oscar

After OpenFn syncs, decision will be reflected in Primero referrals and services

Referrals

Services

When Service subtype information is not specified…

​

If no Service Subtype is selected in Primero…

​

​

Then a default “Type of Service”: “Not Specified” will be sent to OSCaR

​

​

Not Specified

If the OSCaR case worker sees that the Type of Service = “Not Specified”, then they will Reject the referral

and ask the Primero case worker to create and send a new referral with the correct information.

​

Rejected decision is synced back to Primero and “Service Type” is updated to “Other”

​

Flow 2: Oscar -> Primero Caseworker user experience...

Let’s log in...

Oscar staging: http://cif.oscarhq-staging.com/users/sign_in

Oscar email: test@example.com

Password: 123456789��Primero case manager:

Username: mgrbmc

Password: Test2022

​

​

Confidential Open Function Group UNICEF Project

Oscar user creates new client...

User refers client to MoSVY External System (Primero)...

Refer client to “Mosvy External System”

​

User refers specific service to Primero...

Specify referral service details for Primero caseworker

​

Syncing to Primero…

Confidential Open Function Group UNICEF Project

User notified of new or updated cases to review...

Review “New or Updated” cases.�

Focal point user refers case to a caseworker user…

Case “Owner” does not change, but the Province Focal Point case manager user can refer the case to the appropriate caseworker user who should review the new referral.

Caseworker finds the new service to review the referral...

Review the service & update “Referral Status” to accept/reject…

After OpenFn sync…decision is reflected in Oscar referral form

OpenFn Administration: �Quick Refresher

OpenFn Platform: Key Concepts

Projects

Who can access your OpenFn integration setup?

Jobs

What should OpenFn do with the message data?

Triggers

When should OpenFn perform the job?

Credentials

How does OpenFn access your secure systems?

Messages

What data was should OpenFn process?

Runs

How does OpenFn record and report on everything it does?

1

3

4

5

2

6

Confidential Open Function Group UNICEF Project

Let’s log in...

www.openfn.org/login��

Confidential Open Function Group UNICEF Project

Managing jobs...

Confidential Open Function Group UNICEF Project

Flow 1: Primero to Oscar

Get Primero case and referral data (including decisions)

​

Send Primero referral data to Oscar

​

OpenFn jobs map Primero referral data to Oscar and vice versa…

​

given_name: oscarStrings(c.name_first),

family_name: oscarStrings(c.name_last),

gender: oscarStrings(c.sex),

Troubleshooting Basics & �Support

Confidential Open Function Group UNICEF Project

Monitoring Job Runs &�Activity History...

Confidential Open Function Group Version 2.0

OpenFn logs every transaction in Activity History...

Confidential Open Function Group Version 2.0

Review run failures to troubleshoot integration errors...

⚠️ Job run failed…?

Confidential Open Function Group Version 2.0

Click into the run to review the logs...

Exit codes...�0. Success�1. Error (Sync error)�2-5. above (contact OpenFn support)

Confidential Open Function Group Version 2.0

Read the logs to understand the error...

HTTP Status Code: 500s → client errors

The request is missing required fields or incorrectly sending data

Confidential Open Function Group Version 2.0

Read the logs to understand the error...

HTTP Status Code: 500s → server errors

The server failed to fill OpenFn’s request. Need to contact destination system administrator to determine the reason.

Confidential Open Function Group Version 2.0

Read the logs to understand the error...

TypeError → server errors

The job failed to complete the request. Contact OpenFn for support.

Confidential Open Function Group Version 2.0

Turn on notifications to receive email alerts...

When you receive an error email…

�

​

1. Open the email…
2. Read the error message
3. Inspect & Take Action

​

​

​

​

​

Confidential Open Function Group UNICEF Project

Run the job flow again to re-try the sync...

​

1. Click into the [Flow1] job run

​

2. Click “play” next to the failed run�to re-try the flow…��

​

Pulse check:

1. What are OpenFn runs?
2. What can the Activity History be used for?

Change Management

Considerations, validation checks, and examples to keep in mind when making changes in Primero.

​

Confidential Open Function Group Version 2.0

IO Change Management - Best Practices

1. If system or API changes are expected, communicate with all interoperability partners before implementing these changes so that all parties can assess the impact on the interoperability solution and their own systems. Record all changes in the interoperability change log.
2. Update the interoperability “mapping specifications” document if any new field has been modified in the list of data elements to be exchanged
3. After every system change that might impact the API, conduct thorough testing in staging/dev environments before deployment to prod. Also, notify interoperability partners of any testing they may need to conduct on their side.
4. Ensure API documentation is updated after every change (and that these changes have been tested to validate the docs) before sharing with partners and vendors.

​

How to not break the Jobs…�

1. Jobs run automatically, keep them “on”! (admins do not need to edit, only monitor)
2. All fields referenced in the mappings are referenced in the jobs... so before you make any changes to fields, see how they're referenced in the integration.
3. If you need to edit a job or update field mappings → contact support@openfn.org for support

​

​

​

​

​

​

Confidential Open Function Group GRS Project

Managing Users

Administrators can add/remove users to the OpenFn project to support with integration monitoring.

​

Only designated IT administrators should have access. This is not an end-user application.

Confidential Open Function Group Version 2.0

Admin users can add/remove other OpenFn users….

Questions? Forget something? �

Github: https://github.com/OpenFn/unicef-cambodia

�

​

​

​

​

​

​

Confidential Open Function Group UNICEF Project

Managing Credentials

If the system login details change, you may need to update or create a new “Credential” in OpenFn.

Confidential Open Function Group Version 2.0

Confidential Open Function Group Version 2.0

Link jobs to Credentials to define the systems synced ...

Note: You will have different credentials for different environments (production, staging, etc.)

Every Job is linked to 1 credential �

Confidential Open Function Group Version 2.0

View all available Credentials ...

Note that every Credential has an “Owner”.

• Only Owners can view/ edit credential details
• Owners are responsible for updating credentials
• After updating Credentials, link to the relevant job

If authentication details change...

• Credential Owner* will need to update the login details in the OpenFn credential record

​

*We recommend you determine which administrator(s) will be the credential owners.

​

​

​

​

​

​

Confidential Open Function Group UNICEF Project