This section describes some of the portability issues surrounding action definitions. In the Spring 2007 release, some significant enhancements were made that affect the portability of actions. As a result, this section is divided into two parts:
• Click here for Spring 2007 and later releases
• Click here for Summer 2006 and earlier releases
One of the issues that have been encountered since actions were initially introduced is the portability of actions to a different SharePoint site. When a solution is moved to another site, as is the case when a solution template is created and then utilized, or moved from a development environment to a production one, there is a need to enable the actions referenced by the solution to be used with as little modification as possible. There is also the question of how to make action definitions reusable across multiple sites and solutions.
To address these needs and clarify exactly which lists and items will be affected by actions, two enhancements were made to the Actions Wizard for the Spring 07 release.
• Properties were added to the Actions Wizard so that you can identify whether the action should be executed against a specific hard-coded list, or a list with the same name in the site where the action is executed. These are described below, and in each section regarding the creation of action definitions.
• A feature called “Global Links” allows you to define a named variable that represents a URL that you identify. When a change needs to be made, you can update the link in a single location, rather than updating every single action definition that references the URL. For example, say you define a Global Link and call it “Internet-Contacts.” You can use that Global Link in any number of action definitions. If you ever need to update that link, you can simply go to the interface used to create it, make the necessary changes, and the changes will take effect on all actions that reference that link. You don’t have to update the Global Link in every single instance where it is referenced.
The Actions Wizard interface has been modified with the following options:
• Use List Specified Above – Select this option if the action should always be executed against the specific list in the URL identified above this radio button.
• Use List Relative to Site Where Action is Run – Select this option if the action should be executed against the list in whatever site the action is executed from. The action will look for a list with the same name in that site.
NOTE 1: If you use the “Relative” option described above, it is a good idea to make sure all columns referenced by the action definition exist in the corresponding list where the action is executed. If any columns referenced by the action definition do not exist in that list, the action will fail.
NOTE 2: All of the actions utilized in the Spring 07 Solution Set are configured to use the “Relative” option, except where noted in the Setup Guides (available online).
With these new options, action definitions are significantly more portable, reusable, and easy to administer. Consider creating a central library of actions that can be referenced throughout the entire workplace. For example, you could create an “Add New Announcement” action in a central library, configure it to use the “Use List Relative to Site Where Action is Run” option, and use it in any number of solutions. When the action is executed and a new announcement is created, it will always be created in the Announcements list in the site where the action is run. All you need to do is make sure the columns referenced by the action exist in each of the Announcements lists.
Another very reusable, powerful action definition that could be saved in a central actions library is an Email Item Link action. You could define the action to send a custom email, so the user executing the action determines the content and recipient(s). Create the action definition once and use it any number of solutions. If the action ever needs to be updated, the update can be made in just one place, but affect all of the sites that reference the action. It’s not just reusable, it’s easier to ensure consistency.
Global Links are another Spring 07 enhancement that greatly simplifies the process of making actions portable and reusable. A global link is simply an entry in the Central Configuration list that is comprised of a name and a URL. Any time an action is executed that references a global link, it will look up the link to determine the appropriate URL. If the URL ever needs to be updated, it can be done in a single location, rather than trying to remember and access every instance where the URL is referenced.
For example, consider all of the URL references that need to be updated when a solution is moved from a development to a production environment. With global links, you can update the URL references in just one place, versus accessing the Actions tab on every Active Display that references the development URLs. Another potential benefit of Global Links is simplification of the process of creating and referencing actions. Rather than having to find, copy, and then paste a long URL, you can just reference a simple Global Link name.
In order to utilize Global Links, Central Configuration must be enabled as described in the Capabilities Guide. As with all other types of Central Configuration, users must have at least Read access to the Central Configuration list in order to be able to reference or maintain Global Links.
NOTE 1: All of the Global Links are stored in a single item in the Central Configuration list. You do not need to physically access this list in order to maintain the Global Links; this can be done from a link on the Actions Wizard, an Active Displays, or a Cross-Connects. If you do access the Central Configuration list for some other reason, please do not delete or attempt to edit the Global Link entry.
NOTE 2: Do not use the name of a Global Link within the name of an action (e.g., [MyLink]CreateNewTask). This is not supported.
The Global Link maintenance window can be accessed from any active component. The link is located in the top right corner of the Actions Wizard and on the Actions tab of all Active Displays and the Cross-Connect. (If you do not see this link, Central Configuration is not enabled. See Chapter 5 of the Capabilities Guide for instructions to enable Central Configuration.)
1. Place your cursor in the first available row and type the name you want to use for the global link in the first column, surrounded by square brackets as shown in the figure above.
• CorasWorks recommends that you limit the characters in the name to letters and numbers only.
2. Place your cursor in the second column or press Tab and type the full URL to assign to that name. Note that the global links are site-based, not list-based, so just type the URL to the site.
3. Repeat these steps as necessary and then click Submit when you are finished.
• An error message will be presented if you attempt to add a new global link with the same name as an existing Global Link. However, you can have multiple links with different names that point to the same URL.
The Global Link Maintenance Window can also be accessed to modify or delete any of the Global Links. Both the name and the URL can be modified. Any user can use, create, modify, or delete a Global Link, as long as they have the necessary permission to the Central Configuration site and list. Two people will be prevented from modifying the same link at the same time.
• To modify a Global Link, simply make the necessary changes to the entry and click Submit.
• To delete a Global Link, highlight each part of the entry and press Delete or Backspace and then click Submit.
IMPORTANT! If you do need to update or delete a Global Link, keep in mind that it will affect all of the actions and all of the Active Displays that reference that link. If a Global Link is deleted, or if it is modified to point to a URL where the same actions do not exist, you may not be aware of it until a user goes to a page and can no longer execute the actions they used to.
Global Links can be used in two areas of the Actions Wizard. The first location is at the top of the interface, at the prompt for the URL where the action definition is to be saved. When you type the name of a Global Link here and click Add, the list of available document libraries to store the action definition in is updated. The rest of the action definition process is the same.
The second location where a Global Link can be used is in the Configure Action Definition area. Once you have identified the link, the Lists drop-down will be updated appropriately with the available lists in the URL referenced by the Global Link.
Select the desired list and then proceed with the rest of the steps to create or modify an action definition as usual.
NOTE: You cannot use both a Global Link in the Configure Action Definition area and select the Use List Relative to Site Where Action is Run option. The Global Link will override the other option.
This section describes some of the portability issues surrounding action definitions.
There are no portability issues for this type of action, beyond the issues stated for the individual action types that are chained together.
When creating a Create List Item action definition or a Create Item Link action definition, you have the option to select literal (static) values from choice fields and multi-choice fields. If you do this and the selected value does not exist in the Choices collection for that field in the selected Active Display item, the action will fail.
This type of action is not tied to a specific list. The list you identify in the action definition is only used for schema column matching. As long as the list item in the Active Display or Cross-Connect contains the column(s) identified in the action definition, the action will run.
For example, say you create an action and select a list that has a Title column. You type My New Title in the Title field when defining the action and leave all of the other available columns blank. This action can be run on any list item that has a Title field. If you also entered a value in the Description column, the action could only be executed against list items that contain both a Title and Description column.
There are no portability issues for this type of action.
Portability issues may arise if a literal email server is identified in the action definition and is then unreachable when the action is ported to new domain. Issues may also arise if Use SharePoint for Email is selected and email is not configured on the new SharePoint site.
This type of action is not portable. The Spring 07 edition of the Workplace Suite does not support relative URLs for navigation.
When actions were initially deployed, if you deployed an action that was configured to use a list that did not exist in the current configuration, you would have to re-select the appropriate list in the Actions Wizard and then re-enter all of the values for the action definition.
Now, if you deploy an action that is configured to use a list that does not exist in the current configuration, you still have to re-select the appropriate list, but all of the definition values are automatically populated after selecting the list.
There are several ways to configure actions, depending on whether and how you want to use them in multiple solutions and locations.
§ You can create a central actions library and save the action(s) there. Use Global Links to point to that library. As long as Central Configuration is enabled, the action will always be accessible.
§ If you want to ensure that an action is always executed against a specific list in a specific URL, select the “Use List Specified Above” option on the Actions Wizard’s interface when you create the action definition. CorasWorks calls actions that are configured in this way “re-usable.” They are hard-coded to reference a specific list.
§ If you want the action to be executed against a list in the site where the Active Display or Cross-Connect is displayed, select the “Use List Relative to Site Where Action is Run” option when you create the action definition. This will look for the list that is named in the action definition, in whatever site the action happens to be run from. CorasWorks calls actions that are configured in this way “portable.” They can be used in any site, as long as they contain the list named in the action definition, and as long as that list contains the columns referenced in the action.
o Most of the actions in the CorasWorks solution set are configured with the “Use List Relative to Site Where Action is Run” option, except where noted in the Setup Guides (available online).
For all of these action types, the Configure Action section of the Actions Wizard includes a field where the URL of the destination list is identified.
• You
can enter a URL to a site that differs from the site where the Actions Wizard is
located, but is still in the same content database. If you do this, a relative
reference to the identified list is stored.
For example:
The
Actions Wizard is running on a page at http://mysite/sites/jdoe. You select a list
from a site on http://mysite. The reference is
stored as /sites/xyzsite/Lists/mylist. If the action definition is placed on a
new site, the only requirement is that there is a list at
/sites/xyzsite/Lists/mylist. The server name does not matter.
• You
can enter a URL to a different top-level site than the one where the Actions
Wizard is located. If you do this, an absolute reference is stored to the
identified site and destination list. This makes the reference
non-portable if the definition is placed on a server that is not in the same
database as the reference.
For example:
The Actions Wizard is
running on a page at http://mysite/sites/jdoe. You select a
destination list from a site on http://yoursite/sites/you. The reference is
stored as http://yoursite/sites/you/Lists/mylist.
If it did not work this way, the framework would never know to get the list from
a site other than the one the user is on when executing the action. This is not
as portable as the above example.
When creating a Create List Item action definition or Create Item Link action definition, you also have the option to select literal (static) values from choice fields and multi-choice fields. If you do this and the selected value does not exist in the Choices collection for that field in the selected Active Display or Cross-Connect item, the action will fail.
This type of action is not tied to a specific list. The list you identify in the action definition is only used for schema column matching. As long as the list item in the Active Display contains the column(s) identified in the action definition, the action will run.
For example, say you create an action and select a list that has a Title column. You type My New Title in the Title field when defining the action and leave all of the other available columns blank. This action can be run on any list item that has a Title field. If you also entered a value in the Description column, the action could only be executed against list items that contain both a Title and Description column.
There are no portability issues for this type of action.
Portability issues may arise if a literal email server is identified in the action definition and is then unreachable when the action is ported to new domain. Issues may also arise if Use SharePoint for Email is selected and email is not configured on the new SharePoint site.
This type of action is not portable. The Summer 06 release does not support relative URLs for navigation.
When actions were initially deployed in the Winter 2006 release, if you deployed an action that was configured to use a list that did not exist in the current configuration, you would have to re-select the appropriate list in the Actions Wizard and then re-enter all of the values for the action definition.
In the Winter 2006 Update and later releases, if you deploy an action that is configured to use a list that does not exist in the current configuration, you still have to re-select the appropriate list, but all of the definition values are automatically populated after selecting the list.
If you want to be able to reuse an action definition in another area of the same workplace environment, you will need to reconfigure the action to use an absolute URL. The reason is that you will be moving the action definition. When you do this, if it is configured with an absolute URL, when you want to reference it in the new site, it will be immediately reusable without any additional configuration.
You will need to modify the actions in the original source actions library to be an absolute URL reference. Note, however, when working with actions, this configuration will only stay permanent if the display is configured to work with an action library that is not in the same site as the display. Therefore, in certain circumstances, you will have to move either the display to another site first or move the action library to another site and then configure it.
When you select an action to enable for a particular Active Display or Cross-Connect, the Active Display/Cross-Connect web part stores a reference to the location of the action definition. If the action definition is located in a library in the same site where the Active Display or Cross-Connect is located, a reference is stored with just the library name. If the action definition is located in a different site, a reference is stored with the entire path.
If you enable actions for an Active Display or Cross-Connect and then save the site as a site template, the references to action definitions that are stored in action libraries in the same site are maintained and are portable. Any references that include the entire path are not portable.