Creating and Updating an Address Book

This RESTful web service request can be used to create or update a ReportCaster Address Book, which is used by ReportCaster schedules to distribute reports using email, FTP, or a printer.

HTTP Method: POST

REST URL Format:

http://host:port/ibi_apps/rs/ibfs/WFC/Repository/FolderName/AddressBookName

where:

host

Is the name of the system where WebFOCUS is installed.

port

Is the port number used by WebFOCUS.

FolderName

Is the name of the folder where the ReportCaster Address Book is stored. If the folder that is used to store the Address Book exists as a subfolder, then the path to the subfolder name must be included in the REST URL. For example, TopFolderName/SubFolderName.

AddressBookName

Is the name of the ReportCaster Address Book to add or update, which must have a .adr extension.

Body Format:

IBIRS_action=put&IBIRS_object=Object&IBIRS_replace=ReplaceAddressBook&IBIRS_private=MakePrivate&
IBIRS_args=AddEntriesObject

where:

Object

Is the XML object that defines the ReportCaster Address Book.

<rootObject _jt="IBFSCasterObject"
description="AddressBookDescription"
type="CasterDistributionList"><casterObject _jt="CasterAddrBook"
access="AccessType" bookName="AddressBookName"
description="AddressBookDescription" method="Method"
owner="Owner"><destinationList _jt="array"
itemsClass="CasterAddrbookDestinationElement" size="numberOfItems"><item
_jt="CasterAddrbookDestinationElement" burstValue="BurstValue"
burstValueType="BurstValueType" index="indexValue"
location="Location"/></destinationList></casterObject></rootObject>

where:

AddressBookDescription

Is the title for the Address Book.

AccessType

Specifies the security level of an Address Book, which can be set to PUBLIC or PRIVATE. A public Address Book can be viewed by all users, while a private Address Book can be viewed only by the owner and the Administrator.

AddressBookName

Is the name of the Address Book to add or update, which must have a .adr extension. For example, REST_Distribution_List.adr.

Method

Specifies the distribution method for an Address Book, which can be set to FTP, EMAIL, or PRINT.

Owner

Indicates the owner of an Address Book. The user ID specified will be associated with the Address Book as the owner, and will have privileges to view and modify the Address Book.

numberOfItems

Is the number of members that will be added to the Address Book.

BurstValue

If BurstValueType is set to P, then BurstValue is the value used when bursting a report.

If BurstValueType is set to W, then an asterisk (*) and a question mark (?) can be used as wild cards to represent characters at the beginning, end, or middle of the burst values. For example:

a?c*

In this case, all values that start with letter a and have letter c as the third character are returned.

If BurstValueType is set to R, then Java regular expressions can be used to identify strings of text. Precede each instance of a burst value using a Java regular expression. For example:

[bcr]at

In this case, all values that are bat, cat, or rat are returned.

If BurstValueType is set to E, then BurstValue should not have a value.

BurstValueType

Specifies one of the following patterns that is used for BurstValue:

  • P. Plain Text
  • W. Wildcard
  • R. Regular Expression
  • E. Else Send
indexValue

Is a value that starts at 0 and increments by 1 for every member that is added to the Address Book.

Location

Depending on the distribution method, Location may contain an email address, printer destination, or FTP path.

ReplaceAddressbook

Determines whether to update an Address Book. Select one of the following options:

MakePrivate

Determines whether to make an Address Book private. Specify true or false.

AddEntriesObject (optional)

Is the XML object that is used to indicate that additional entries are to be added to the Address Book. The Address Book must first be retrieved and the additional entries must be included within the destinationList tags as part of the Object definition for IBIRS_object. The existing entries in the Address Book do not have to be included within the destinationList tags. IBIRS_replace should be set to true.

<object _jt="HashMap">
<entry>
<key _jt="string" value="insertitems"/>
<value _jt="string" value="true"/>
</entry>
</object>

Example 1:

In this example:

POST Request URL:

http://localhost:8080/ibi_apps/rs/ibfs/WFC/Repository/RESTful_Web_Services/
Car_Reports/REST_Distribution_List.adr

Body:

IBIRS_action=put&IBIRS_object=<rootObject
_jt="IBFSCasterObject" description="REST Distribution List"
type="CasterDistributionList"><casterObject _jt="CasterAddrBook"
access="PRIVATE" bookName="REST_Distribution_List.adr" description="REST
Distribution List" method="EMAIL" owner="admin"><destinationList
_jt="array" itemsClass="CasterAddrbookDestinationElement" size="2"><item
_jt="CasterAddrbookDestinationElement" burstValue="" burstValueType="E"
index="0" location="other@informationbuilders.com"/><item
_jt="CasterAddrbookDestinationElement" burstValue="JAPAN"
burstValueType="P" index="1"
location="rest@informationbuilders.com"/></destinationList></casterObject
></rootObject>&IBIRS_replace=false&IBIRS_private=true

Response:

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<ibfsrpc _jt="IBFSResponseObject" language="EN" name="put" returncode="10000" returndesc="SUCCESS" subreturncode="0" subsystem="SSYS" type="simple">
	<ibfsparams size="5">
		<entry key="IBIRS_replace" value="false"/>
		<entry key="IBIRS_private" value="true"/>
		<entry key="IBIRS_object" value="&lt;rootObject _jt=&quot;IBFSCasterObject&quot; description=&quot;REST Distribution List&quot; type=&quot;CasterDistributionList&quot;&gt;&lt;casterObject _jt=&quot;CasterAddrBook&quot; access=&quot;PRIVATE&quot; bookName=&quot;REST_Distribution_List.adr&quot; description=&quot;REST Distribution List&quot; method=&quot;EMAIL&quot; owner=&quot;admin&quot;&gt;&lt;destinationList _jt=&quot;array&quot; itemsClass=&quot;CasterAddrbookDestinationElement&quot; size=&quot;2&quot;&gt;&lt;item _jt=&quot;CasterAddrbookDestinationElement&quot; burstValue=&quot;&quot; burstValueType=&quot;E&quot; index=&quot;0&quot; location=&quot;other@informationbuilders.com&quot;/&gt;&lt;item _jt=&quot;CasterAddrbookDestinationElement&quot; burstValue=&quot;JAPAN&quot; burstValueType=&quot;P&quot; index=&quot;1&quot; location=&quot;rest@informationbuilders.com&quot;/&gt;&lt;/destinationLis
t&gt;&lt;/casterObject&gt;&lt;/rootObject&gt; "/>
		<entry key="IBIRS_args" value="__null"/>
		<entry key="IBIRS_" value="/WFC/Repository/RESTful_Web_Services/Car_Reports/REST_Distribution_List.adr"/>
	</ibfsparams>
	<rootObject _jt="IBFSCasterObject" defaultLng="en_US" description="REST Distribution List" dummy="false" extension="adr" externalId="1a7ddf0eIff6aI4886Ibde9I77c691d280a0" fullPath="/WFC/Repository/RESTful_Web_Services/
Car_Reports/REST_Distribution_List.adr" handle="1a7ddf0eIff6aI4886Ibde9I77c691d280a0" length="0" name="REST_Distribution_List.adr" policy="////D///9+f/////f/////////8AAAA=" rsPath="/ibi_apps/rs/ibfs/WFC/Repository/RESTful_Web_Services/Car_Reports
/REST_Distribution_List.adr" type="CasterDistributionList">
		<nlsValues _jt="HashMap" loadFactor="0.75" threshold="12">
			<entry>
				<key _jt="string" value="en_US"/>
				<value _jt="ArrayList" size="1">
					<item _jt="string" index="0" value="REST Distribution List"/>
				</value>
			</entry>
		</nlsValues>
		<properties size="3">
			<entry key="id" value="1a7ddf0eIff6aI4886Ibde9I77c691d280a0"/>
			<entry key="tool" value="addressbook"/>
			<entry key="method" value="EMAIL"/>
		</properties>
		<casterObject _jt="CasterAddrBook" access="PRIVATE" bookName="REST_Distribution_List.adr" burstValue="false" description="REST Distribution List" ibfsId="1a7ddf0eIff6aI4886Ibde9I77c691d280a0" ibfsPath="" id="1a7ddf0eIff6aI4886Ibde9I77c691d280a0" method="EMAIL" owner="admin" policy="open,delete,rename,|,security;makeRules;viewRules" sendMethod="EMAIL" summary="">
			<destinationList _jt="array" itemsClass="CasterAddrbookDestinationElement" size="2">
				<item _jt="CasterAddrbookDestinationElement" burstValue="" burstValueType="E" index="0" location="other@informationbuilders.com"/>
				<item _jt="CasterAddrbookDestinationElement" burstValue="JAPAN" burstValueType="P" index="1" location="rest@informationbuilders.com"/>
			</destinationList>
		</casterObject>
	</rootObject>
</ibfsrpc>

If the value for the returncode attribute in the XML response is 10000, then the Address Book was successfully added.

Example 2:

In this example:

The following REST URL retrieves an existing Address Book:

http://localhost:8080/ibi_apps/rs/ibfs/WFC/Repository/RESTful_Web_Services/Car_Reports/
REST_Distribution_List.adr?IBIRS_action=get

POST Request URL:

http://localhost:8080/ibi_apps/rs/ibfs/WFC/Repository/RESTful_Web_Services/Car_Reports/
REST_Distribution_List.adr

Body:

IBIRS_action=put&IBIRS_object=<rootObject
_jt="IBFSCasterObject" binary="false" createdOn="1350862349237"
defaultLng="en_US" description="REST Distribution List" dummy="false"
effectiveRSName="EDASERVE" extension="adr"
externalId="1a7ddf0eIff6aI4886Ibde9I77c691d280a0"
fullPath="IBFS:/WFC/Repository/RESTful_Web_Services/Car_Reports/REST_Dist
ribution_List.adr" handle="1a7ddf0eIff6aI4886Ibde9I77c691d280a0"
lastModified="1350862349237" lastaccessBy="admin"
lastaccessOn="1350862566520" length="0" name="REST_Distribution_List.adr"
ownerId="10001" ownerName="admin" ownerType="U"
policy="//3/D///9+f/////f/////////8AAAA=" returnedLng="en_US"
rsPath="/ibi_apps/rs/ibfs/WFC/Repository/RESTful_Web_Services/Car_Reports
/REST_Distribution_List.adr" signedOn="true"
type="CasterDistributionList"><nlsValues _jt="HashMap" loadFactor="0.75"
threshold="12"><entry><key _jt="string" value="en_US"/><value
_jt="ArrayList" size="2"><item _jt="string" index="0" value="REST
Distribution List"/></value></entry></nlsValues><properties
size="3"><entry key="id"
value="1a7ddf0eIff6aI4886Ibde9I77c691d280a0"/><entry key="tool"
value="addressbook"/><entry key="method"
value="EMAIL"/></properties><casterObject _jt="CasterAddrBook"
access="PRIVATE" bookName="REST_Distribution_List.adr" burstValue="false"
description="REST Distribution List"
ibfsId="1a7ddf0eIff6aI4886Ibde9I77c691d280a0"
ibfsPath="IBFS:/WFC/Repository/RESTful_Web_Services/Car_Reports"
id="1a7ddf0eIff6aI4886Ibde9I77c691d280a0" method="EMAIL" owner="admin"
policy="open,delete,rename,|,security;makeRules;viewRules"
sendMethod="EMAIL"><destinationList _jt="array"
itemsClass="CasterAddrbookDestinationElement" size="2"><item
_jt="CasterAddrbookDestinationElement" burstValue="" burstValueType="E"
index="0" location="other@informationbuilders.com"/><item
_jt="CasterAddrbookDestinationElement" burstValue="ITALY"
burstValueType="P" index="1"
location="rest@informationbuilders.com"/></destinationList></casterObject
></rootObject>&IBIRS_replace=true&IBIRS_private=true

Response:

If the value for the returncode attribute in the XML response is 10000, then the Address Book was successfully updated.

Example 3:

In this example:

The following REST URL retrieves an existing Address Book:

http://localhost:8080/ibi_apps/rs/ibfs/WFC/Repository/RESTful_Web_Services/Car_Reports/REST_Distribution_List.adr?IBIRS_action=get

POST Request URL:

http://localhost:8080/ibi_apps/rs/ibfs/WFC/Repository/RESTful_Web_Services/Car_Reports/REST_Distribution_List.adr

Body:

IBIRS_action=put&IBIRS_object= <rootObject _jt="IBFSCasterObject" createdOn="1393510291277" defaultLng="en_US" description="REST Distribution List" dummy="false" effectiveRSName="EDASERVE" extension="adr" externalId="f7c08730I4adfI4c8aIb109I8e014fac5a23" fullPath="IBFS:/WFC/Repository/RESTful_Web_Services/Car_Reports/REST_Distribution_List.adr" handle="f7c08730I4adfI4c8aIb109I8e014fac5a23" inheritedPrivacy="true" lastModified="1393510291277" lastaccessBy="admin" lastaccessOn="1393510324927" length="0" name="REST_Distribution_List.adr" ownerId="10001" ownerName="admin" ownerType="U" policy="//7/w////38f9////v9////////+AAAA" returnedLng="en_US" rsPath="/ibi_apps/rs/ibfs/WFC/Repository/RESTful_Web_Services/Car_Reports/REST_Distribution_List.adr" type="CasterDistributionList"><properties size="3"><entry key="id" value="f7c08730I4adfI4c8aIb109I8e014fac5a23"/><entry key="tool" value="addressbook"/><entry key="method" value="EMAIL"/></properties><nlsValues _jt="HashMap" loadFactor="0.75" threshold="12"><entry><key _jt="string" value="en_US"/><value _jt="ArrayList" size="2"><item _jt="string" index="0" value="REST Distribution List"/></value></entry></nlsValues><casterObject _jt="CasterAddrBook" access="PRIVATE" bookName="REST_Distribution_List.adr" burstValue="false" description="REST Distribution List" ibfsId="f7c08730I4adfI4c8aIb109I8e014fac5a23" ibfsPath="IBFS:/WFC/Repository/RESTful_Web_Services/Car_Reports" id="f7c08730I4adfI4c8aIb109I8e014fac5a23" method="EMAIL" owner="admin" policy="open,delete,rename,|,security;makeRules;viewRules" sendMethod="EMAIL"><destinationList _jt="array" itemsClass="CasterAddrbookDestinationElement" size="2"><item _jt="CasterAddrbookDestinationElement" burstValue="ENGLAND" burstValueType="P" index="0" location="rest2@informationbuilders.com"/><item _jt="CasterAddrbookDestinationElement" burstValue="FRANCE" burstValueType="P" index="1" location="rest3@informationbuilders.com"/></destinationList></casterObject></rootObject>&IBIRS_replace=true&
IBIRS_private=true&IBIRS_args=<object _jt="HashMap">
<entry><key _jt="string" value="insertitems"/><value _jt="string" value="true"/></entry></object>

Response:

If the value for the returncode attribute in the XML response is 10000, then the additional entries were successfully added to the Address Book.


Information Builders