International Aid Transparency Initiative (IATI) Publishing: Customization Options

This page covers:

Overview 

In this setup guide, system administrators and implementing consultants will learn to:

• Enable IATI XML generation in Amp Impact

• Set up the environment for entry of IATI data

• Modify Amp Impact default interfaces to include IATI-specific information

After following this guide, a Salesforce environment will be set up so that it can automatically take its impact and transaction data, entered through Amp Impact, and print out an IATI standard XML file with that data. Clients can take that XML and publish it directly to the IATI registry.

Terminology

IATI: The International Aid Transparency Initiative (IATI) is a global initiative to improve the transparency of development and humanitarian resources and their results to address poverty and crises.

Organisation Standard: The IATI organisational standard is used to describe one or more organisations involved in any stage development cooperation (funding, implementing etc.). It is designed to report forward-looking aggregate budget information for the reported organisations, and planned future budgets to recipient institutions or countries. 

The IATI organisational standard is also used to report links to relevant public documents. Organisations publish this data in an organisation file. It is expected that every organisation publishing IATI data should include one organisation file, which is updated at least annually.

Activity Standard: The IATI activity standard is designed for reporting the details of individual development cooperation activities/projects. An activity is defined by the reporting organisation. Depending on who is reporting, it might be a large program, a small project, or another logical grouping of work and resources.

The IATI activity standard is the most widely used part of IATI. The activity standard supports around forty different fields, referenced by standard codelists, and designed to capture information about many different kinds of aid activities. Organisations publish this data in an activity file. It is expected that every organisation publishing IATI data should include one or more activity files. An activity file can detail one or many activities, and an organisation can publish one or many files.

Provide IATI Users with Field/Object Permissions

For Users to generate their IATI XML file through Amp, they will need additional permissions to ensure they have access to the data relevant to IATI reporting. This access is not provided out-of-the-box for all Amp Users.

Assign IATI Permission Set to IATI Users

After installing Amp Impact and enabling the IATI feature, follow these steps to ensure your IATI Users have access to all IATI objects and fields. 

1. Go to the Setup Quick Search box, and enter “Permission Sets”.

2. Select the “IATI Full Access” Permission Set.

3. Click the Manage Assignments button.

4. Click the Add Assignments button.

5. Select all relevant users that should have access to the IATI Full Access Permission Set and click “Assign”.

If an IATI User does not need access to all IATI objects and fields, the IATI_Full_Access permission set can be cloned, and object/field permissions that are not necessary can be removed from the cloned permission set.

Add Permissions for IATI Fields to User Profiles/Custom Permission Sets

Due to a Salesforce limitation on packaging permissions for objects that are detail in a master-detail relationship to standard Salesforce objects, the permissions for two objects ‒ ampi__Organization_Role__c and ampi__Project_Role__c ‒ and their fields must be added manually to either the user profile or a custom permission set, depending on the environment and use case. 

Below is the list of objects/fields for which permissions must be manually set:

Enable Customize Application Permission for Direct Read Access to Custom Metadata Types

The Customize Application Permission is required for direct read access to Custom Metadata Types. This follows Salesforce’s rollout of the “secure by default” approach. For more information on its use in Amp Impact, see Set Defaults for IATI XMLs.

To grant a profile or permission set read access to a custom metadata type:

1. Go to the profile or permission set that you want to grant access to.

2. Under Enabled Custom Metadata Type Access, click Edit, as shown in screenshot below.

3. Add the custom metadata type, ampi.IATI Default Contact and ampi.IATI Default Reporting Org, to the list of Enabled Custom Metadata Types. See screenshot below.

To re-enable read access to custom metadata outside of Apex code or system mode contexts, see the following steps:

1. In Setup, navigate to Schema Settings.

2. Deselect Restrict access to custom metadata.

Enable XML Generation from Accounts

Account is the central object from which both the IATI Organisation and IATI Activity XMLs will be generated. In order to generate the XML files, some setup is required on the Account page layout to enable Users to generate their IATI files.

Create/Customize Flow from Template

By default, Amp contains a Screen Flow that Users will interact with to:

1. Select whether they are creating the XML file according to the IATI Organisation Standard or the IATI Activity Standard,

2. If the XML is being generated according to the IATI Activity Standard, filter the Activities (ampi__Project__c records) that will be printed into the XML.

   1. By default, the only filter that is available for use is to either display all records, or only records where ampi__Ready_For_IATI_Reporting__c = TRUE.

If the Screen Flow must be customized (e.g. text changed, filter options added), then this Flow can be cloned and modified for those customizations. 

Customize Flow Filters (Activity Standard only)

This step is only required if the filters for the Activity Standard XML in the Screen Flow need to be customized. In order to customize these filters, follow the steps below:

1. Go to Setup.

2. Type and select “Flows” in the QuickSearch menu.

3. Open the IATI_XML_Generation Flow in Flow Builder.

4. Modify the available filters in the Filter_IATI_Activities Screen element.

5. Ensure that the filter criteria is reflected in the Filtered_IATI_Activities Get Records element.

6. Click Save As.

7. In the Save screen, select to save as a New Flow.

Create Lightning Action to Launch Custom Flow

If a custom flow has been created for IATI XML generation, then a new Lightning Action must be created to launch that flow from an Account record.

1. Go to Setup.

2. Go to Object Manager.

3. In Object Manager, select Account.

4. Go to Buttons, Links, and Actions.

5. Click New Action to create a Flow Action, selecting the custom flow created. The Label and Name can be filled out per the use case.

2. (Required) Add Lightning Quick Action to Account Record Page

To ensure that Users can open the Flow that generates the IATI XML files, the Lightning Quick Action that launches the Flow must be added to the Account page layout.

1. Go to Setup.

2. Go to Object Manager.

3. In Object Manager, select Account.

4. Go to Page Layouts.

5. Click into the Page Layout that will be assigned to the Profile(s) of Users who will be generating XML files for IATI reporting.

6. In the top menu, select Mobile & Lightning Actions. From the options that appear, drag and drop Generate IATI XML into the page layout.

7. Click Save.

Set Defaults for IATI XMLs

Create Default Reporting Organisation

If only one organisation will be the reporting organisation for all the IATI XML files generated from a single Salesforce environment, the organisation’s details can be set as the default for all the IATI files so that the information does not need to be entered for each IATI Activity.

1. Open Setup.

2. Use the Quick Find search to find and open Custom Metadata Types.

3. Click “Manage Records” next to “IATI Default Reporting Org”.

4. In the list displayed, click the “New” button to create the IATI Default Reporting Organisation.

5. In the edit view:

   1. Set the Label field to the name of the Organisation. When clicking out of the input box, this will automatically set the IATI Default Reporting Organisation Name.

   2. Enter the IATI Organisation Identifier. This must be the unique Id provided by IATI to the reporting organisation. For more information on Organisation Identifiers, read here.

If no default Reporting Organisation is set, then the parent Organisation (Account) for an Activity (ampi__Project__c) will be printed as the Reporting Organisation for that Activity.

Create Default Contact

If there is only one individual whose contact information will be used for all IATI Activity XML files generated from a single Salesforce environment, that contact information can be set as the default for all the IATI files so that the information does not need to be entered for each IATI Activity file.

1. Open Setup.

2. Use the Quick Find search to find and open Custom Metadata Types.

3. Click “Manage Records” next to “IATI Default Contact”.

4. In the list displayed, click the “New” button to create the IATI Default Contact.

5. In the edit view:

   1. Set the Label field to the name of the Contact. When clicking out of the input box, this will automatically set the IATI Default Contact Name.

   2. Enter the IATI Organisation. This must be the text name of the Organisation to contact for more information about an Activity.

   3. Enter the IATI Organisation Department.

   4. All other fields are optional.

If no default Contact is set, then the related Contact (ampi__Project_Role__c) marked as the IATI Reporter (ampi__Is_IATI_Reporter__c = TRUE) for an Activity (ampi__Project__c) will be printed as the Contact for that Activity.

Set Up Environment for IATI Data Entry

Depending on the reporting requirements of an organisation, the default page layouts and field labels in Amp Impact can be modified to ensure that those requirements are met while creating or updating data.

Update Page Layouts to Include IATI Fields and Related Lists

• The objects mentioned in the IATI Data Entry Mapping Sheet contain IATI-specific fields that can be printed into the generated XML file. 

• The fields in the IATI Data Entry Mapping Sheet need to be added into the respective page layouts so that values can be entered for IATI reporting.

• Apart from the fields, there are some related lists that need to be added to some of the Objects. These can be found in the table below. Please make sure these can be found on the object page.

Add or Override Help Text for IATI Reporting

To support users in entering data required for IATI reporting, help text on all IATI-specific fields has been added by default. For fields that are not IATI-specific, help text may be added or modified to provide additional context to users, as indicated in the table below:

Translate Amp Terminology to IATI Terminology

Override Amp Labels with IATI Terms

Amp Impact and IATI use different terminology to describe different artifacts in M&E. The table below provides the default labels of objects and fields in Amp Impact, and their corresponding IATI term. Using Translation Workbench, organisations can override the default Amp labels with IATI terminology.

Add IATI Fields to Field Sets

To facilitate IATI data entry through Amp Impact, certain field sets can be modified to include IATI fields for population. Those field sets are listed below:

Picklist Limitation for IATI Reporting

Due to the codes generated and printed into the IATI XML files by populating picklist fields, there is a limitation around customizing any of these fields. For any picklist field used for IATI reporting, the picklist values can only be edited in the Label and not in the API Name in order for the corresponding code to print correctly. 

Find below the list of picklist fields used in IATI reporting with this limitation:

Set Up Named Credential for IATI XML Validation

In order to validate the IATI Organisation or Activity XML while it is being generated, a Named Credential record will need to be created in order to connect an Amp Impact environment with the IATI Validator. Before you can create this, you will first need to obtain an IATI Gateway API Key.

Create IATI Gateway API Keys

1. Navigate to https://developer.iatistandard.org

2. Click “Sign Up”.

3. Follow the sign up process and confirm your account from an email link.

4. Sign In to the API Gateway developer portal (same URL as above).

5. Click Subscriptions > “Exploratory”/“Full Access” (as per requirement).

6. Enter a Subscription Name (this can be anything you want) in the box.

7. Check the box to agree to the Terms of Use.

8. Click the Subscribe Button.

9. Copy your Primary or Secondary Key from your Profile on the API Gateway webpage.

Create Named Credential Record in Salesforce

With the primary and secondary keys copied from the previous section, you are now ready to create a Named Credential record to connect Salesforce and Amp Impact to the IATI Public Validator.

1. Go to setup and search for “Named Credentials”.

2. Click on “External Credentials” and then click on “New”.

3. Fill in the following details and click Save.

a. Label: IATI VALIDATOR EXTERNAL CREDS

b. Name: IATI_VALIDATOR_EXTERNAL_CREDS

c. Authentication Protocol: Custom

4. Create a Permission Set Mapping for the External Credential. This Permission Set Mapping will help to authorize users such that users assigned to this permission set will only be allowed to utilize a specific OcpApimSubscriptionKey provided by the IATI. 

5. Input the OcpApimSubscriptionKey (Primary or Secondary Key) provided by the API Gateway in the value field of Parameter 1 and click Save.

6. Create a custom header with the following inputs. 

• Name: Ocp-Apim-Subscription-Key

• {!$Credential.IATI_VALIDATOR_EXTERNAL_CREDS.OcpApimSubscriptionKey}

• Sequence Number: 1

7. Now, create a Named Credential, with the following parameters.

• Label: IATI VALIDATOR

• Name: IATI_VALIDATOR

• URL: https://api.iatistandard.org

• External Credential: IATI VALIDATOR EXTERNAL CREDS

• Allowed Namespaces: ampi

8. Create a new custom header within the Named Credential with the following parameters:

• Name: Content-Type

• Value: text/plain

• Sequence Number: 1