Getting and setting attributes and values
This page will teach you how to retrieve and modify u-forms on the mast basic level - by getting and setting their attributes and values.
By now, you need to have one of the Repository APIs up and running. This documentation assumes that you are using the Python API, partly because this enables you to enter commands one at a time in the Python interpreter, which is probably the easiest step-by-step way to use the repository.
Other APIs work similarly. Feel free to add caveats to this, anyone ...
Seeing a u-form
Connecting to your local repository
To start with, you need to tell your Python interpreter to use a repository. The best way to do this on your local machine is to install a copy of the Civium Workbench. While the Workbench is running, a local repository will be actively running to support it. You must configure the Workbench's repository to accept commands from the Python API by adding the line APIServicePort = 6200 to your settings.cfg file. Then run the Workbench, and then at you Python interpreter issue the command
>>> r = repos.Repository('localhost:6200')
What does this do? It uses the MAYA library module repos to create a repository object called r. The address of this repository is given by the argument localhost:6200 because this is the port you told the Workbench to open for the purpose of servicing API requests.
If this command doesn't work for you, it may because you didn't import the repos module from the Python API. As described on the Python API page, this can be done by using the command from MAYA.VIA import repos. You should probably import uform and uuid while you're at it.
Authenticating
Before asking the repository for information using listAttr (see below), it's necessary to authenticate.
In the Python interpreter, issue the following four commands in order:
>>> from MAYA.VIA import uform >>> f=uform.UForm() >>> f['client_type']=['authenticated',1] >>> r.authenticate(f)
Listing the attributes of a u-form
Now you have a repository and the means to issue commands to it, try asking it for information from the u-form for the country Trinidad and Tobago, by typing (or hopefully just copying and pasting!) the command
>>> r.listAttr( uuid._('~01a7c66766786311d79a4611d0198c3fee') )
This command requests a list of the attributes of the u-form whose UUID is ~01a7c66766786311d79a4611d0198c3fee. This happens to be the UUID for Trinidad and Tobago - how on earth you would know this seemingly random string of characters will be discussed later in the sections on collections and indexes.
The UUID itself is wrapped up in the strange looking syntax uuid._( ..... ) . This tells the Python interpreter to use the MAYA library module uuid to interpret the string enclosed in the brackets as a UUID, and the whole string uuid._('~01a7c66766786311d79a4611d0198c3fee') ) as a Python object representing that UUID.
Thus, once you have a repository object r and a uuid string blah, you should be able to get a list of the attributes contained in the u-form with this uuid by issuing the command
>>> r.listAttr( uuid._('blah') )
This is one of the most basic ways to see 'what kind of stuff' is contained in a given u-form.
Why didn't it work the first time?
Now, if you typed in the syntax correctly, you were probably met with the disappointing response
[]
which is the Python interpreter telling you that the list of attributes you requested is just an empty list. Unless there is a special reason why your local repository already had a copy of this u-form, all this tells you is that there is no information about this u-form present at the moment. Do not be dismayed - if you repeat the command, you should get a much more satisfying response like
>>> r.listAttr( uuid._('~01a7c66766786311d79a4611d0198c3fee'))
['iana_code', 'iso_code_numeric3', 'creator', 'fips_code', 'flag_image', 'shepherd_signature',
'parent_subdivision', 'roles', 'image_data', 'iso_code', 'child_subdivision_name',
'feature_type', 'area', 'label', 'source', 'shepherd_versions', 'population_date', 'latitude',
'iso_code_alpha3', 'description', 'un_region', 'subdivision_type', 'members', 'date',
'adm_regions_misc', 'population', 'publisher', 'name', 'language', 'rights', 'country',
'region', 'administrative_level', 'longitude', 'name_**']
This looks much more like a list of some of the attributes a country should possess.
Why were the results so different? It is because the first time you issued the r.listAttr command, the u-form wasn't present in your local repository. However, when the repository replied saying "I haven't got any attributes for this u-form", it also submitted a request to the Information Commons saying "if any repository anywhere has a u-form with this UUID, can I have a copy?" By the time you issued the command a second time, this request had (hopefully) been met and the u-form was in your local repository all ready for you.
The Information Commons is a highly distributed information environment, and the model rests crucially on the idea of shepherding u-forms from one place to another. Shepherding is another important topic that will be discussed later.
The getAttr and setAttr commands
At the heart of our repository implementation is the ability to get and set attributes. This is carried out using the commands getAttr and setAttr, which are part of the MAYA/VIA/repos module in the Python API.
getAttr
Suppose that your repository object is called r. The command for getting attributes is
>>> r.getAttr( uuid , attribute )
For example, the command
>>> r.getAttr( uuid._('~01a7c66766786311d79a4611d0198c3fee'), 'name' )
should give the result
'TRINIDAD AND TOBAGO'
(If it doesn't, try repeating the command to see if the u-form was initially absent but was then shepherded to your local repository because of your first request.)
As an exercise, you should now try to find other information about Trinidad and Tobago, such as its population and language. To do this, you might want to list the attributes using the listAttr command, and you may even have to follow a link and explore another u-form or two to be able to find the name of the language.
setAttr
The setAttr command is very similar, only this time you're not asking the repository for information, you're giving the repository information. Instead of giving an attribute and asking for its value, you are giving both the attribute and the value. The syntax for this is as follows:
>>> r.setAttr( uuid , attribute, value )
For example, suppose you want to assert that the capital city of Trinidad and Tobago is called 'Port of Spain'. You can add this information to the u-form we have already by issuing the command to the repository
r.setAttr( uuid._('~01a7c66766786311d79a4611d0198c3fee'), 'capital_city', 'Port of Spain')
You will see a 0 at your Python command line if this command succeeded. Try getting the new attribute using the getAttr command to see if it worked.
Strengths and weaknesses
In a traditional relational database, if a database of countries wasn't created with a field for capital_city, then you can't add it later without redesigning the whole database. But in the Information Commons, it's simple - you just say that you want to set a new attribute-value pair, and it becomes part of the existing u-form. Whether anybody has written software to make use of this information is a different question entirely - one of the reasons we have a carefully designed role system is to make sure that software running off the Information Commons knows precisely how to interpret the attributes and values available.
In practise, the example above is not a good way to represent capital cities - if we add information about capital cities to the Information Commons (as we certainly will do, and may have done by the time you read this documentation), we would want to represent the populated place Port of Spain as a separate u-form with its own UUID and attributes such as name, population, etc. In this case, the capital_city attribute in the Trinidad and Tobago u-form should contain the UUID of the u-form for Port of Spain, from which we could learn not only the city's name, but also its latitude and longitude and other information needed to represent the city accurately.
This raises information architecture, authorship and design questions quite clearly - if anyone can contribute to the Information Commons, how do we ensure that certain information can be definitive and not be overwritten? These are important questions which we will address separately.
-
In fact, we need to address these questions here in order for this documentation to work! How can we give learners a sandbox to experiment with so that their experiments won't have been done by a previous user and won't harm definitive data?
-
Mike suggested that we may provide a 'sandbox' UUID that anyone can right extend and that everyone should know is up for grabs.
The next step
Once you have mastered the art of getting and setting individual attributes and values, move on to creating and editing entirely new u-forms.
Back to CiviumDocumentation
