International Aid Transparency Initiative (IATI) Publishing: Customization Options

This page covers:

Overview of IATI Publishing with Amp Impact

IATI Publishing in Amp Impact allows organizations to take its impact and transaction data in Amp Impact, generate an IATI standard XML file, and publish it directly to the IATI registry. In this guide, we’ll cover the five steps to set up IATI Publishing in Amp Impact:

IATI Terminology Overview

Before we get into the weeds, let’s align on a couple of IATI-specific terms.

IATI Field & Object Permission Configuration

IATI field- and object-level access is not assigned out-of-the-box and there are a few configuration steps to ensure that the right users have the access and permissions they need to manage the IATI publishing process.

Assign IATI Permission Set to IATI Users

Amp Impact comes with the “IATI Full Access” permission set that can be assigned to users that need access to all the related IATI fields and object. To assign this permission set, first enable the IATI feature and then follow these steps to assign the permission set:

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, object- and field-level permission for ampi__Organization_Role__c and ampi__Project_Role__c must be assigned manually. There are two options for adding permissions to these objects:

1. Manually add these objects and fields to the relevant profiles;

2. [Recommended] Create a customer permission set to provide access to these objects and fields and assign this to the relevant users.

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

   

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 types”.

   

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.

   

(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 organization, 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.

   1. Label: IATI VALIDATOR EXTERNAL CREDS

   2. Name: IATI_VALIDATOR_EXTERNAL_CREDS

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

   1. Name: Ocp-Apim-Subscription-Key

   2. {!$Credential.IATI_VALIDATOR_EXTERNAL_CREDS.OcpApimSubscriptionKey}

   3. Sequence Number: 1

   

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

   1. Label: IATI VALIDATOR

   2. Name: IATI_VALIDATOR

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

   4. External Credential: IATI VALIDATOR EXTERNAL CREDS

   5. Allowed Namespaces: ampi

      

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

   1. Name: Content-Type

   2. Value: text/plain

   3. Sequence Number: 1