Managing Contacts!

Create your application for self updating contacts

You can develop a new WhereIsNow™ client application able to manage self updating contacts in a new, fast and simply way.

 

Before starting, please read Self Updating Contacts page on this site.

 

Technically speaking, a WhereIsNow™ contact document is nothing else an XML file which contains the updated information about your address, phone or mobile phone number, operator, email, Skype contact and much more.

 

How can you create a WhereIsNow™ contact document? Currently you can:

• use the form on the WhereIsNow™ site (click here); you can choose to save it on the WhereIsNow™ servers or to generate the XML file in order to copy and publish it everywhere on the web.
• build yourself an XML file matching the ContactSchemaDefinition.xsd xml schema, a set of rules to which an XML document must conform in order to be considered compatible with different WhereIsNow™ applications; you need also to use the map.xml, an XML file describing values contained in your contact document. You can download these resources querying WhereIsNow™ Web Service with keys: ( [1] - [34]) for ContactSchemaDefinition.xsd, ( [1] - [17]) for map.xml.

 

Your own application should be able to handle and update an address book with few essential operations:

• using the contact document keys, it can query the WhereIsNow™ Web Service to get link to the newest version (it is very likely that in many cases the contact file is not public, so develop your application to provide the client's credentials via https);
• get the contact document at the link provided by the WHereIsNow™ Web Service (remember, the file can be published on the WHereIsNow™ web site or wherever the publisher decided to and that it is very likely that the contact file is not public, so develop your application to provide the client's credentials via https also for this request);
• parse the contact file; refer to the map.xml file to understand the values of the fields contained into the contact file.

 

Let's see them in details.

 

Request to WhereIsNow™ Web Service

Click here to refer completely dedicated session to WhereIsNow™ Web Service.

 

Getting Updated Contact file

A WhereIsNow™ publisher can decide to publish her/his contact document on the WhereIsNow™ servers, or in any other location on the web. According to the cases, operations to execute can be different.

 

If a contact document is available from the WhereIsNow™ site, the Web Service returns a link like the following:

 

https://www.whereisnow.com/secure/GetContact.now?token=edc301af583f476b28f1v09z0de95e19d1973cec

 

WhereIsNow™ platform process the Token and the user credentials, your application will have to send them in GET or POST with parameter names "username" and "password". Password can be sent in clear text or in SHA1 encoded format.

 

Otherwise, if a contact document is not published on WhereIsNow™, refer to the contact document publisher to know access politics. We suggest our publisher to use the same "username" and "password" fields to check the user's credentials on their pages and, for a security reason, to provide an https access to it.

 

Resources description

• map.xml contains the description of the fields of the contact document. For example: parameter <id>2</id> contained in a contact file, is described on map.xml as

  
  <param>

  <name>First Name</name>	<!-- Field name -->
  <idWIN>2</idWIN>	<!-- Relative ID in Contact document -->
  <keyField>106</keyField>	<!-- PIM ID -->
  <keyAttribute>1</keyAttribute>	<!-- PIM Attribute ID -->
  <keyIndex>0</keyIndex>	<!-- Multiple field ID -->
  <icon></icon>	<!-- Relative Icon of current field -->

  </param>

  The fields keyField and keyAttribute are inherent to the native address book's fields contained on any device which supports Java PIM Library (API jsr 75).

   

  The keyFIeld contains the "PIM ID" which identifies the correspondent field on the native phone address book for a given device (mobile phone, smart phone, organizer,... ). The keyAttribute contains the "PIM Attribute ID" which contains additional information concerning the PIM ID: i.e. address field has PIM ID equal to 100 on any device which supports Java PIM Library (API jsr 75); the street attribute of the address complex field has ID 2, the postalcode attribute ID has instead a value of 5. If a field does not match any native fields on the device address book, PIM IDs are equal to zero ( MSN, Skype, Facebook, etc).

   

  The keyIndex contains the "Multiple field ID", which gives an order to elements sharing the same keys: i.e. we want to enable users to specify more than one mobile phone number; in the map.xml there are two mobile phone fields with the same PIM IDs, but we set keyIndexes to 0 for the first number and to 1 for the second one. In these cases, field with lower keyIndex has priority and is considered as the most used.

 

• ContactSchemaDefinition.xsd can be used to validate XML in Contact documents.

Parsing updated contact file

Now you are able to extract and manage the information contained in the self updating contact files. What are you waiting for? Let's start to build your great application!!!