Transform Hub Guidelines
The transform hub is Paterva's integration with third party data sources of all kinds. Items where users do not need to purchase any API keys or subscription data from a data vendor can be added to both the Community and Commercial Maltego hubs. Commercial items can ONLY be added to the Commercial Maltego hub.
All hub items will need to be reviewed by Paterva and are subject to not being included in either of the hubs. Please carefully review the guidelines below to ensure that your transforms conform with our standards. Additionally commercial items will need to have an agreement in place with Paterva.
Consider that your transforms should be useful to a large audience. In other words - if your transforms do a reverse phone book lookup for the 20 people of Timbuktu it is probably not that useful for the rest of the world. If it's everyone in the UK - different story.
Nobody likes to play with transforms that don't work. If your transforms are not tested properly, don't submit them. Rather test it a little more and then submit. If people start complaining that your transforms are not working we're going to remove them (after speaking to you of course). Broken transforms make you look bad, and by association, make us/Maltego look bad.
If your transforms break or do not function as expected, or the user is using it incorrectly then please ensure that your transforms return meaningful feedback to the user. Don't assume they'll know what to do. Also – please set the verbosity of the error message to an acceptable level. Nobody wants to see fatal messages that result in a pop-up all the time.
Remember that your transforms are now in front of everyone with a Maltego client. You might have tested it with a group of 10 friends that know how they work, but don't assume that everyone will figure it out. Document how to use it, preferably with a case study and a walk-through. Or a video.
Please use the URLs and descriptions in the transform hub. Make sure the links work and that the content on the pages are relevant.
If your transform is using API keys and/or credentials ensure that it's easy for users to register and that the registration process works well. We prefer that you use the fields provided in the transform hub specification and map these to transform settings.
If your transforms require an API key or registration please ensure that you state that clearly in the meta data. When the key / credentials are not present or wrong please return a 600 error - this will tell the client to ask the user to supply a new or valid key/credentials. People will install the transforms and if they don't work out the box you'll have confused users. Confused users are normally angry users.
Where possible use the standard Maltego entities. This would mean that user can run other transforms on your results. Avoid 'dead-end' entities - these are entities where no transforms can run on - they tend to become leaf nodes. Furthermore – when extending the entity's definition try to re-use fields if they already exist and when they don't make sure that they are defined in the entity's definition and are not dynamically added by the transform. This allows users to start with a fully capable entity. If you don't understand what this means you need to either contact us, or think about it a little more (definitely take a look at our best practices for entities. Data modelling is the most important part of writing Maltego transforms. Plan it carefully and it will save you a lot of time in the long run. Make use of transform settings and entity properties - it's there for a reason! Also refer to the list of standard entities and their properties/fields before you start!
Name your transform similarly. In the context menu transforms are sorted by transform name. As such it makes sense to start your transforms all with the same two or three letters. E.g. FTblah and FTmoo for the Forensics Tool blah and moo transforms. Do not name your transforms too generic – e.g. MaltegoMoo or MaltegoBlah. That’s just silly. Your transforms are not the only transforms!
The transform hub will only really work if users can explore your transforms for free (or at least with a trial). Making everything paid for is the quickest way the transform hub will die.
The webpage where your transforms are described should probably also contain some licensing information. Nobody wants to read or write it… but it might become important one day!
We did not build the transform hub so that we can increase our support channel by 200%! ;) The email address for support (in meta info) should be checked by yourself. We’ll pass on any support queries we get, but the real hope is that user will contact you directly. If we get a lot of angry emails and you don’t respond to users we’ll have to remove you off the hub.
Group your entities in one group and call it something that is closely connected to your project name. Having 3 groups with 2 entities in each is no fun. Yes...we know we do it but then again, we've been at it for many years. Because Maltego currently does not delete entities upon uninstall (there good reasons for this - think shared entities) you should make it easy for the user to see which entities are connected to your project.
For developers to have their transforms listed on the transform hub the following fields are required:
|Field||What it Means||Example|
|* Name||Name of your transforms||IMDB transforms|
|* Seed URL||Where the seed of your transforms are location (URL). You can optionally ask that this not be visible in the GUI as well. If this is not specified it will not be displayed.||http://transf.moviesrus.com/seed.xml|
|* Description (short)||A short description of your transforms.||Query the Internet Movie Database|
|* Description (long)||A longer description of your transforms.||This set of transforms allows you to pivot from movie, director and actor.|
|Modified||A Unix timestamp of when this entry was last modified||474336000|
|* Icon (URL)||A 48x48px PNG icon for your transforms.||http://www.moviesrus.com/myicon.png|
|* Provider Name||You / your company name.||MoviesRUs|
|* Provider website||Where users can read about you and your transforms.||http://www.moviesrus.com/transforms/|
|*Provider email||Where users can email email@example.com|
|Provider phone||Where users can phone you. Let's hope they don't.||555-123-1234|
|Registration URL||If users need to register for the transforms this page should explains the process to them.||http://www.moviesrus.com/transforms/register.php|
|Input Fields||If you want to perform access control on your transforms (e.g. make it commercial) these are the fields you'll use in your transforms to identify users. Fields have the following properties:
||See example below|
|Pricing info||Explain to users how much your transforms cost (if at all).||$0.01 per transform|
|Pricing website||At this website they'll pay / enter CC info.||http://www.moviesrus.com/pricing.php|
Below is an example of transform hub XML, please note this is CaSe SeNsItIvE.
<Seed Pos="10" Display="Commercial TAS v3"> <Url Visible="true">https://alpine.paterva.com/CTAS31.xml</Url> <!--visible is optional, default "false"--> <Description>This is a short description.</Description> <Details>This can be a very very very very very long description. This can be a very very very very very long description.</Details> <Modified>1417531063521</Modified> <!-- unix time --> <Icon><!-- 48x48px png--> <Url>https://www.paterva.com/web7/images/menu/menu5.png</Url> </Icon> <Provider> <Name>Paterva</Name> <Website>www.paterva.com</Website> <Email>firstname.lastname@example.org</Email> <Phone>+27 555 5555</Phone> </Provider> <Registration> <Website>http://register.paterva.com</Website> </Registration> <Pricing> <Info>$1 per transform or $100 per month unlimited transforms.</Info> <Website>https://pay.paterva.com</Website> </Pricing> <Inputs> <!-- Examples... --> <Input Name="api-key" Display="API Key" Type="string" Optional="true" Auth="true"/> <Input Name="username" Display="User Name" Type="string" Auth="true"/> <!-- default for Optional and Auth is "false" --> <Input Name="password" Display="Password" Type="string" Auth="true"/> <Input Name="service-url" Display="Main Blah URL" Type="url" Optional="true" DefaultValue="http://some.service.com/blah"/> <Input Name="from" Display="Start Date" Type="date" Optional="true" DefaultValue="1999-04-22"/> <Input Name="netblockSize" Display="Netblock Size" Type="string" Optional="false" DefaultValue="10"/> </Inputs> </Seed>
If your transform returns the following XML it will result in the Maltego client popping up an useful error message prompting the user to fill out the fields marked as 'Auth' (as defined in the transform hub item).
An example of this can be seen below:
<maltegomessage> <maltegotransformexceptionmessage> <exceptions> <exception code="600">Your error message such as API key required</exception> </exceptions> </maltegotransformexceptionmessage> </maltegomessage>
The transform hub offers what we believe to be the simplest way to give Maltego users access to your transforms as well as install these into the client. The 5 images below show the install process from start to finish:
© Copyright 2017, Paterva PTY Limited