Learning & Support


Migration tool: issue-based to article-based

Twixl Support Team Updated: - Created :

    Issue-based apps have become deprecated in May 2021. Until June 30th, 2021, you can still migrate existing issue-based apps to article-based by using our easy migration tool. This article tells you all about it!

    How to use the migration tool?

    When you go to an issue-based app on the Twixl platform, you'll notice a warning message Convert to article-based.

    Convert to an article-based app: this will start the actual conversion process.


    During the migration process, your issue-based app will be locked. As such, you will not be able to alter your issue-based app or upload new issues during the conversion progress. There will, however, not be any impact for existing users of your app. Note that even if the app has already been converted, you still have the option to repeat the process.

    What will be converted for you?

    A conversion will do the following things:

    1. A new article-based app will be created with the same settings as your issue-based app (and the same mode, Development or Production).
    2. All Subscriptions, Notifications and Entitlements Settings will be converted.
    3. PDF Issues will be converted into a Collection with a PDF Content Item.
    4. Twixl Issues (InDesign-based .publications) will be converted into a Collection of .article content items.
    5. We'll create basic Browse Grid and Item Styles for you, in order to mimic the look and feel of a legacy issue-based app (a kiosk). A special Item Style will also be created to mimic the Featured Issue.
    6. The Browser Client will also be automatically configured for you.
    7. The custom url scheme tp-store://show will be interpreted as tp-collection://root (see Custom URL Schemes for article-based apps for more info).


    You can of course still change all imported settings afterwards! All browse grid styles and item styles are editable, as they are for any app!


    There is a difference in the way entitled content is being handled in issue-based apps and article-based app.

    • For issue-based apps: no thumbnails are visible for unentitled content.  
    • For article-based apps: thumbnails are visible for unentitled content and a reader will need to login after tapping/clicking on the content that requires entitlements.

    Build Settings

    If you choose to upload and import the Build Setting of your issue-based app, which we strongly recommend to make the conversion process easier, the following extra things will be imported:

    • General: The App Store Application ID will be imported, to maintain the Smart Banner.
    • Entitlements: Additional settings will be imported.
    • Google Analytics: Your Google Analytics keys will be imported.
    • User Interface: Tool Bar colors and Scroller Background settings will be imported.
    • Sharing: All Sharing settings will be converted.
    • User interface: The Grid Text Color will be imported.


    After you have gone through the whole migration process, you still need to build and publish an update of your app.



    In an issue-based app, an issue has one dedicated WebResources folder. It contains all the dependencies for your Web viewers and Web overlay buttons.

    As mentioned above, Twixl Issues (.publication files) will be converted into a Collection of separate Twixl-articles (.article files). The Migration Tool will scan every .article inside every issue:

    • If a .article contains a link to the WebResources folder, the complete WebResources folder of the old Issue will be copied and assigned to that Twixl Article. The reason is because we have no way of tracking which dependency (residing in the WebResources folder) is being used in which Twixl article.
    • If a .article contains no link to the WebResources folder, the WebResources of the old Issue will not be copied to that .article.

    As a result – if you need to convert issues – your article-based app will be bigger than your issue-based app. However – in general – this will not influence the reading-experience of your article-based app. Readers don't need to download the complete Collection, they will be downloading each .article on demand.

    In some cases where your issues contain a lot interactive elements and huge WebResources folder, this can however be problematic. The advice below could then become very useful.

    Sidenote: Similar behaviour is also used in the way we Export content from within the Twixl Publisher InDesign plugin.


    The advice below requires you to have access to the original native InDesign-files!

    1. Use this Migration Tool. Even though it doesn't cover everything, it's a good start. The existing structure of your issue-based app will be converted (other things as well). This will save you a lot of time!
    2. Next step: optimise the existing content, based on the worst cases (read: the biggest Content Items). We provide a tool for that, our built-in reports has a section called App Size, that we enhanced with a handy feature: the report will list the biggest Collections on top. For each Collection you can then (if you click on the Collection) see a on overview of all the Content Items. Again with the biggest files on top. If a Collection has individual Content Items with a file size about 100MB, we don't see a problem. Readers will download those in a snap. See this KB-article for more info.
    3. Based on that report, the next step would be to optimise the problematic content and upload it again. In other words: you replace the existing converted content on the Twixl Distribution Platform by your own optimised content. The following steps are important:
      1. Optimising layout: Evaluate the book-files and try to eliminate unnecessary content. Maybe this is the time to adjust the concept and layout a little bit. Try to think outside the box and reinvent your design. This is a good opportunity!
      2. Optimising export: Once you optimised the content, you can also optimise the export. We advise you to use Export as separate articles. See this KB-article: Export
        1. On a Mac, you can then right-click on every .article file, select Show Package Contents and delete unneeded items in the WebResources folder of each individual .article file. You could use a search-command (via the Terminal or something else) to do this faster.
        2. On Windows, a .article file is displayed as a normal folder. You can delete unneeded items in the WebResources folder for each individual .article file. You could use a search-command (via the Windows Shell or something else) to do this faster.
      3. Uploading the new content: Once you are done optimising, it's then time to upload and replace the content on the Twixl Distribution Platform. 
        1. You can upload them individually, if there are not of lot of them.
        2. You could choose to use the Publication Composer to combine the separate .articles into one .publication again. This way you can upload new content per Collection (use the Import .publication tool on the Twixl Distribution Platform). Don't forget to delete the old content (mark it is unpublished first, so you can differentiate it easier). See this KB-article for more info.
        3. You can also use the Admin API to mass-upload new content. See this documentation: Integration API


    The Admin API is a paid option. See our Pricing page for more info.

    What won't be converted for you?

    • The Info Page and Info Cell are not converted automatically. You can still create a new 'web viewer' content item to achieve a similar result.
    • Categories and Sections will not be converted. You can organize the collections in your article-based app in such a way that you obtain a similar result.

    Was this article helpful?

    1 out of 2 found this helpful