custom.md

Creating Packages

Creating new packages

Custom packages can be used to group your own actions, manage default parameters and share entities with other users.

Let's demonstrate how to do this now using the ibmcloud fn CLI tool…

1. Create a package called "custom".

   ibmcloud fn package create custom

   ok: created package custom
   

2. Get a summary of the package.

   ibmcloud fn package get --summary custom

   package /myNamespace/custom
     (parameters: none defined)
   

   Notice that the package is empty.

3. Create a file called identity.js that contains the following action code. This action returns all input parameters.

   function main(args) { return args; }

4. Create an identity action in the custom package.

   ibmcloud fn action create custom/identity identity.js

   ok: created action custom/identity
   

   Creating an action in a package requires that you prefix the action name with a package name.

5. Get a summary of the package again.

   ibmcloud fn package get --summary custom

   package /myNamespace/custom
    (parameters: none defined)
   action /myNamespace/custom/identity
    (parameters: none defined)
   

   You can see the custom/identity action in your namespace now.

6. Invoke the action in the package.

   ibmcloud fn action invoke --result custom/identity

   {}
   

Setting default package parameters

You can set default parameters for all the entities in a package. You do this by setting package-level parameters that are inherited by all actions in the package.

To see how this works, try the following example:

1. Update the custom package with two parameters: city and country.

   ibmcloud fn package update custom --param city Austin --param country USA

   ok: updated package custom
   

2. Display the parameters in the package and action, and see how the identity action in the package inherits parameters from the package.

   ibmcloud fn package get custom

   ok: got package custom
   ...
   "parameters": [
      {
          "key": "city",
          "value": "Austin"
      },
      {
          "key": "country",
          "value": "USA"
      }
   ]
   ...

   ibmcloud fn action get custom/identity

   ok: got action custom/identity
   ...
   "parameters": [
      {
          "key": "city",
          "value": "Austin"
      },
      {
          "key": "country",
          "value": "USA"
      }
   ]
   ...

3. Invoke the identity action without any parameters to verify that the action indeed inherits the parameters.

   ibmcloud fn action invoke --result custom/identity

   {
      "city": "Austin",
      "country": "USA"
   }

4. Invoke the identity action with some parameters.

   ibmcloud fn action invoke --result custom/identity --param city Dallas --param state Texas

   {
      "city": "Dallas",
      "country": "USA",
      "state": "Texas"
   }

{% hint style="info" %} Invocation parameters are merged with the package parameters with the invocation parameters overriding the package parameters. {% endhint %}

Sharing packages

After the actions and feeds that comprise a package are debugged and tested, the package can be shared with all OpenWhisk users. Sharing the package makes it possible for the users to bind the package, invoke actions in the package, and author OpenWhisk rules and sequence actions.

1. Share the package with all users:

   ibmcloud fn package update custom --shared yes

   ok: updated package custom
   

2. Display the publish property of the package to verify that it is now true.

   ibmcloud fn package get custom

   ok: got package custom
   

   {
      ...
      "name": "custom",
      "publish": true,
      ...
   }

   Others can now use your custom package, including binding to the package or directly invoking an action in it. Other users must know the fully qualified names of the package to bind it or invoke actions in it. Actions and feeds within a shared package are public. If the package is private, then all of its contents are also private.

3. Get a description of the package to show the fully qualified names of the package and action.

   ibmcloud fn package get --summary custom

   package /myNamespace/custom: Returns a result based on parameters city and country
     (parameters: *city, *country)
   action /myNamespace/custom/identity
     (parameters: none defined)
   

   In the previous example, you're working with the myNamespace namespace, and this namespace appears in the fully qualified name.

{% hint style="success" %} 🎉 Congratulations on sharing your first public Package! 🎉 {% endhint %}