Blog

Custom Behaviors for PAPI

Introducing Custom Behaviors for Property Manager/PAPI

April 26, 2018 by Jay Sikkeland

Advanced metadata serves an important role in the configuration ecosystem, providing custom functionality that cannot be configured via Akamai product features alone.  See the advanced metadata overview for more details on advanced metadata.

However, advanced metadata as it’s typically used does have some known weaknesses (spoiler alert: we can help you address them). Those weaknesses include:

  • You cannot add, edit, copy, delete, or move advanced metadata.
  • Akamai professional services are required to add, edit and delete advanced metadata in your configs before you can activate them. This requirement can halt the integration of Akamai configs.
  • When professional services are required to intervene in advanced metadata situations, automated DevOps processes often get interrupted and can break down.

With those challenges in mind, imagine being able to:

  • Create a library of reusable metadata snippets
  • Add advanced metadata to Property Manager configs yourself
  • Instrument your DevOps automation to include Akamai configs

Introducing Custom Behaviors

Custom Behaviors is a new capability in Akamai’s Property Manager (PM) that addresses most of the problems with advanced metadata, providing a library of customer-specific functionality that's available via self-service. It is included free of charge with any product that is configured using Property Manager.

How it works

First, work with your Akamai account team to identify reusable advanced metadata snippets and to enable them as Custom Behaviors for your account.  The snippets can be instrumented with input/output variables to make them more reusable.

Once enabled, you insert the Custom Behaviors into Property Manager by clicking the Add Behavior button and selecting Custom Behavior.

You then choose the Custom Behavior you want from the drop-down list.  The Property Manager UI shows a short description as well as the actual metadata XML.

In PAPI, you add a Custom Behavior by inserting the following json in your config rule tree:

 

{     "name": "customBehavior",     "options": {          "behaviorId": "cbe_1111"     } }

There is a separate PAPI endpoint (GET /papi/v1/custom-behaviors) which retrieves a list of available behaviorIDs.

 

{     "accountId": "act_1234",     "customBehaviors": {         "items": [             {                 "behaviorId": "cbe_1111",                 "description": "This behavior does this",                 "name": "Custom Failover",                 "status": "ACTIVE",                 "sharingLevel": "ACCOUNT",                 "updatedByUser": "person1",                 "approvedByUser": "person2@akamai.com",                 "updatedDate": "2017-06-16T21:18:53Z",                 "xml": "<comment:info>some metadata goes here</comment:info>"             },             {                 "behaviorId": "cbe_2222",                 "description": "This behavior does that",                 "name": "Special AWS Origin Authentication",                 "status": "ACTIVE",                 "sharingLevel": "PARTNER",                 "updatedByUser": "person1",                 "approvedByUser": "person2@akamai.com",                 "updatedDate": "2017-06-16T21:19:50Z",                 "xml": "<comment:info>some other metadata goes here</comment:info>"             },             etc...

 

What about Custom Override Rules and Advanced Matches?

Custom Override Rules are special advanced metadata snippets that must execute last in the config, usually to override certain built-in Property Manager functionality.  Custom Override Rules are supported with Custom Behaviors and work almost exactly the same way, except you add a Rule and select Custom Override instead of adding a Behavior and selecting Custom Behavior.  There is a separate PAPI endpoint (GET /papi/v1/custom-overrides) to retrieve a list of available overrideIDs.

Advanced Matches will be handled differently.  We are including additional matches to account for the majority of use cases requiring Advanced Matches:

  • Match on request type

    <match:request.type>

  • Add AKAMAI_TRANSLATE (purge) to request method match

    <match:request.method>

  • Match on metadata stage

    <match:metadata-stage>

  • Match on regular expression (coming soon)

    <match:regex>

 

What if a Custom Behavior needs to be upgraded or removed?

There is currently no automatic versioning for Custom Behaviors, but if an update is required, your account representative can create a new Custom Behavior and add "v2" to the name, for instance, if you have "Behavior Foo", we can create a new one and call it "Behavior Foo v2".

To use the new Custom Behavior, you have to edit each Property Manager config where the old one is used and select the new Custom Behavior from the drop-down list, , then save the config and activate.

With PAPI, you would first need to obtain the new behaviorID

 

GET /papi/v1/custom-behaviors

to download the config version rule tree, replace the old behaviorID with the new one, and upload the rule tree. PAPI will automatically pull in the new/updated Custom Behavior XML.

Depending on the reason why the old Custom Behavior needed to be upgraded or removed, your account representative may lock or delete the old Custom Behavior, by setting the status to LOCKED or DELETED.

LOCKED - You will get a warning message in Property Manager that the Custom Behavior shouldn't be used anymore, but you can keep using it if necessary. LOCKED status is typically used when the Custom Behavior works and is still safe to use, but there is a better alternative available.

DELETED - The Custom Behavior will no longer appear in the drop-down list and you will get an error in Property Manager (and PAPI) that prevents you from saving the config. At this point, you will have to change to a different Custom Behavior or remove it altogether.  (Note: DELETED status is used when the Custom Behavior shouldn't be used anymore due to erroneous or unsafe metadata. You can still reactivate old Property Manager config versions, even if they contain a DELETED Custom Behavior.)

 

How do I get started?

Please reach out to your account team if you have advanced metadata that you would like to reuse. An account team technical representative will review the metadata to make sure it’s safe and appropriate for reuse, and possibly suggest refactoring by splitting the metadata into smaller snippets or using variables to make it more reusable.

Professional services fees may apply depending on the quantity, complexity and the amount of refactoring required.  But after the one-time initial setup is completed, you can reuse the Custom Behaviors across all your configs.

For PAPI users, the PAPI documentation has more details.

Jay Sikkeland is a senior product manager at Akamai Technologies.

 

Categories: