Why should you use a Library folder when sharing Metrics?

Creating powerful applications in Pigment can make a big impact on your processes and insights, but the real power of the platform comes from sharing data between these applications and across teams and functions. The way we do this in Pigment is through shared blocks using the Libraries functionality. You can read more about that here.

However, as the complexity of your model grows and you have more and more data being shared between applications, it can be difficult to keep track of what is pushing from where and pulling into what. Tools like the dependency diagram can help, but we find it’s easier to create a bit of redundancy to clarify the data flow and to protect the data.

What's a library folder?

The library folder is NOT the same as the Libraries section of your settings. Instead, it is a simple folder you create within your application, in the block section of the sidebar (click here to learn where we recommend creating it). This is then used to store Metrics for:

1. Any data you want to share to another application in your workspace (“Push_Metric Name”)

2. Any data coming into your application from another application in your workspace (“Pull_Metric Name”)

You can create the Library folder like any other folder in your application side bar. To avoid creating too much redundancy, I would recommend only doing these steps for any application outputs that will be used as inputs in another application (no need to do it for shared Metrics from the Hub used for general settings like the “Switchover Date”, “FX rate”, ...). 

Why creating a library folder?

Model clarity & easier references

When opening the library folder in the application, you instantly see the Metrics used for data inflows that are necessary to this application process, as well as the outflows that are feeding other applications (and therefore other processes). This information is extremely valuable as it gives clear context to the application’s own processes, as well as how it interacts with the workspace as a whole.

Sanitising blocks for use elsewhere

Having this extra Library step is also the perfect opportunity to focus more on the shared Metrics and add or remove dimensions to make sure they are properly dimensioned. For example, when I'm sharing my staff cost metric from my Workforce application, I only need to share data at the cost center level. I can use this step to remove the employee level, or other dimensions that are only needed or relevant within the application but shouldn't be shared outside it. 

Taking a few minutes to ask ourselves these questions and make the appropriate adjustments is also a way to avoid making errors and having wrong numbers elsewhere. And even if you’re already asking these questions and considering the answers, using the library folder gives you a clear place to go for those actions, so you don’t have to keep track of where you made certain changes related to sharing the data.

Better security

Using the library to stage shared Metrics is also a great way to manage the security between applications. Your library folder and the Metrics in the Libraries tool should match perfectly, and it will be easy to spot any anomalies.

The library folder is also the perfect place to reset the access rights for your Pull Metrics. With the previous example, I want my Business Managers to be able to display staff costs at cost center level in a different application. Because they don't have access to the Workforce application, they won't be able to see any staff costs data if I don’t reset the AR (see article on AR inheritance here). To solve this, I can use the resetaccessrights() function on the shared metric (the Pull version) in the library folder of the application where it is being used.

How to manage a Library folder?

Any time you have a Metric you would like to share to another application, here is the process:

1. Duplicate the Metric and remove “- copy” from the end of the name

2. Add “Push_” to the beginning of the name (click here to learn more about our naming convention recommendations)

3. Move the new Push Metric to the Library folder

4. Replace the original formula with a simple reference to the original Metric you duplicated

5. Use the Remove modifier to remove any dimensions from the Metric you don’t want to be usable outside the current application. Don’t forget to remove those dimensions from the structure of the metric as well.

6. Share the Push Metric to the Libraries database in the settings of the metric

Now a sanitised version of the Metric will be available throughout your workspace! Congrats!

Now for pulling a Metric into your application:

1. Access the Libraries tool from within your application’s settings

2. Toggle the button next to the application you would like to pull data from

3. You can now reference the Push Metric in your application from the Playground and create a new Pull_Metric located in the Library folder from this application

4. Use this step to add dimensions that are needed to perform calculations or to display certain results by using the ADD modifier and changing the structure of the Pull Metric (example: add the Currency dimension and map the Push Metric on USD)

You can now use this Pull Metric with the appropriate structure in your application!

In just a moment, we’ll talk about how to make sure your Pull Metrics can be used correctly, but first let’s take another quick look at the examples below:

Examples: 

Pull_WF_Staff Costs ($): Metric with staff costs data in $ from the Workforce Planning application

Push_TP_New Revenue ($): Metric with new revenue in $ from the Topline Planning application

End-to-end example

I want to use my staff costs that I calculated in my Workforce Planning application to consolidate a full P&L view in my P&L Reporting application:

Step 0: In the Workforce Planning application I have an output Metric with my total staff costs named: EE_Total Staff Costs ($).

Structure of the Metric: Employee, Contract Type, Cost Center, Month, Version

Step 1: Create a staging Metric in my Library folder in my Workforce application named: Push_WF_EE_Total Staff Costs ($).
Structure of the Metric: Cost Center, Month, Version

We don’t need to keep the Contact Type and the Employee in the structure as we don’t want to share this level of granularity by sharing this Metric.

Formula: ‘Push_WF_EE_Total Staff Costs ($)’ = ‘EE_Total Staff Costs ($)’[remove: Employee, Contact Type]
 

Step 2: Share the “Push” Metric from the settings of the Metric, thus making sure I only share the relevant data and the minimum number of dimensions with the Metric

Step 3: In the receiving application Library settings, activate the library of the Workforce Planning application to be able to reference the Push Metric

Step 4: Create a new Metric named: Pull_WF_EE_Total Staff Costs ($)
Structure of the Metric: Cost Center, Month, Version, Currency
 

In my formula bar I need to resetaccessrights() that are inherited from the Workforce application (only a security admin can allow this function to be used, read this to know more about resetaccessrights()) and add the currency dimension:

Formula: ‘Pull_WF_EE_Total Staff Costs ($)’ = resetaccessrights(‘Push_WF_EE_Total Staff Costs ($)’)[BY: Currency.”USD”]
 

Step 4: This Pull Metric in now ready to use in my P&L Reporting application 

What limitations?

Typically, shared Metrics are used for outputs Metrics. For this reason, there are occasions when the structure of your application may change, and you will need to reflect these changes in your Push metric as well. This is an extra step (and one you must be sure to remember), but it’s a good opportunity to make sure the dimensions changes are handled properly in light of the new structure and appropriately propagated to the other applications on your workspace.

Another limitation is when you find yourself with so many shared blocks that it defeats the purpose of having them in one easy-to-reference place. In this instance, the best practice is to look for a way to only share a reduced number of metrics that we will be able to split later on (we would rather share a Nexus metric containing all our data than sharing each of our P&L metrics one by one). We can also split up the library folder into at least two – one Push and one Pull – or possibly even into separate Pull folders for other applications or use cases. Another option could be to only create Push Metric, but not the Pull ones. The drawback is that you have to go to the library settings to see your applications inflows and the Metrics used might not be well dimensioned and ready to be used as it’s the case for the Pull Metrics. But it’s a good way to reduce the redundancy if it’s your priority.

Recap

Library folders are useful for managing blocks shared between applications. To use one effectively:

• Arrange the library at the top of your application folder structure for easy access

• Create Push copies of the relevant blocks and sanitise them for use outside the application

• Turn on the sharing of those Push metrics rather than the original ones

• Create Pull metrics in the library folder of the destination application, and use that metric to reset access rights before use

• Use appropriate naming conventions to help you keep track of these Push and Pull metrics

• Make sure you bake it into your process to review these library folders when changing metric structures so any changes are accurately reflected